Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.particle.pro/llms.txt

Use this file to discover all available pages before exploring further.

The Particle Pro MCP server lives at https://mcp.particle.pro and lets AI agents — Claude Code, Claude Desktop, Cursor, ChatGPT Desktop, and any other MCP-aware client — call Particle’s podcast, knowledge-graph, company, and advertising tools directly. Setup is a one-time browser approval; everything else is automated by the agent.

​
Connect your agent

claude mcp add --transport http particle-pro https://mcp.particle.pro
Claude Desktop UI alternative: Settings → Connectors → Add custom connector, paste https://mcp.particle.pro, complete OAuth in the browser. Easier than editing JSON and avoids the mcp-remote bridge.
The first tool call triggers an OAuth flow: your client opens the authorize URL in a browser, you sign in to Particle Pro and pick the project the agent should act as, and your client exchanges the resulting code for a token automatically. See the Quickstart for a step-by-step walk-through and a sanity-check call, or Authentication for the full OAuth 2.1 spec.

​
What’s in the box

13 tools across four namespaces:

Entities

Resolve people, organizations, and places to canonical slugs; navigate the topic taxonomy.

Companies

Resolve and inspect companies — products, competitors, identifiers (slug, ticker, domain, CIK, QID).

Podcasts

Search dialogue, list episodes and clips, pull entity mentions, and bundle full episode overviews.

Advertising

Sponsor analytics — per-company ad presence, per-podcast sponsor lists, cross-catalog leaderboard.
Endpointhttps://mcp.particle.pro
TransportStreamable HTTP
AuthenticationOAuth 2.1 — see Authentication
Tool count13 across 4 namespaces
Read/writeRead-only (every tool advertises readOnlyHint: true)

​
How it differs from the REST API

The REST API and the MCP server share a single backing process and the same handlers. The differences:
  • Shape. Each MCP tool returns one markdown text content block. The REST API returns JSON. If you need typed JSON for programmatic use, hit the underlying REST endpoint linked from each tool page.
  • Bundling. Some MCP tools roll up multiple REST calls (e.g. podcasts/get_episode can also fetch top entities, segments, and the transcript when the matching include_* flags are set). REST endpoints are single-resource.
  • Identifiers. MCP tools always accept the agent-facing slug (entity_slug, company_slug, podcast_slug, episode_slug). The REST API accepts the same slugs alongside encoded canonical IDs.
  • Auth. MCP requires an OAuth 2.1 access token bound to https://mcp.particle.pro as its aud claim. The REST API accepts API keys or platform JWTs. See Authentication.
  • Errors. MCP tools surface errors as isError: true results with a human-readable message rather than HTTP problem-details bodies. See Errors.

​
When to use which surface

  • Building an agent (Claude Code, Cursor, Claude Desktop, custom MCP client)? Use the MCP server. The bundled tool responses, slug-first inputs, and markdown rendering are designed for agent loops.
  • Building a service (server-to-server, scheduled job, frontend)? Use the REST API. Fine-grained control, OpenAPI schema, predictable payloads.
  • Both surfaces talk to the same database, the same search ranking, and the same billing meter, so mixing them within one organization is fine.

​
Discovery

Agents that follow the MCP / OAuth specs discover everything they need from the resource:
  • https://mcp.particle.pro/.well-known/oauth-protected-resource — RFC 9728 protected-resource metadata pointing at the AS.
  • A 401 from the MCP endpoint carries WWW-Authenticate: Bearer realm="mcp", error="...", resource_metadata="..." so unauthenticated clients can bootstrap.
The Authorization Server’s metadata document at https://api.particle.pro/.well-known/oauth-authorization-server carries the rest (token endpoint, registration endpoint, supported scopes, JWKS URI).

​
Next steps

Quickstart

Step-by-step setup with troubleshooting for each client.

Authentication

OAuth 2.1 end-to-end: discovery, registration, PKCE, refresh, revocation.

Tool reference

Every tool, every input, every output.

Errors

How tool errors surface and how agents should react.