> ## 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.
# Particle Pro MCP server
> An OAuth-secured MCP server that exposes Particle's podcast, knowledge graph, company, and advertising surfaces as tool calls for AI agents.
The Particle Pro [MCP](https://modelcontextprotocol.io) 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
**One-click install:** [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=particle\&config=eyJ1cmwiOiJodHRwczovL21jcC5wYXJ0aWNsZS5wcm8ifQ%3D%3D) · [Add to VS Code](https://vscode.dev/redirect/mcp/install?name=particle\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.particle.pro%22%7D) — or use the matching manual config below.
```bash Claude Code theme={"dark"}
claude mcp add --transport http particle https://mcp.particle.pro
```
```json Claude Desktop theme={"dark"}
// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
//
// Claude Desktop's claude_desktop_config.json doesn't accept a bare `url`.
// Bridge the remote server through `mcp-remote`, which opens a browser
// for OAuth and proxies stdio ↔ Streamable HTTP. Restart Claude Desktop
// after editing.
{
"mcpServers": {
"particle": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.particle.pro"]
}
}
}
```
```json Cursor theme={"dark"}
// ~/.cursor/mcp.json
{
"mcpServers": {
"particle": {
"url": "https://mcp.particle.pro"
}
}
}
```
```json VS Code theme={"dark"}
// .vscode/mcp.json
{
"servers": {
"particle": {
"type": "http",
"url": "https://mcp.particle.pro"
}
}
}
```
```bash mcp-remote (any stdio-only client) theme={"dark"}
# Bridges a stdio MCP client to a remote OAuth-secured Streamable HTTP server.
npx -y mcp-remote 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.
**ChatGPT:** Settings → **Apps** → Advanced settings → enable **Developer mode** (requires a Pro, Plus, Business, Enterprise, or Edu plan) → **Create app** with `https://mcp.particle.pro` and complete OAuth in the browser. See the [Quickstart](/mcp/quickstart#chatgpt) for the step-by-step flow.
**Any other MCP client:** point it at `https://mcp.particle.pro` over Streamable HTTP and prefer OAuth if the client supports it; stdio-only clients can bridge through `mcp-remote` (last tab above).
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](/mcp/quickstart) for a step-by-step walk-through and a sanity-check call, or [Authentication](/mcp/authentication) for the full OAuth 2.1 spec.
## What's in the box
25 tools, organized into **exposure categories**. A bare connection advertises the six default categories plus the always-on `system` meta-tools; five more categories are **opt-in** (advertised only when you select them with the `?include=` selector). Either way, **every public tool is callable by name** regardless of what was advertised — see [Tool sets & discovery](/mcp/tool-sets).
Default categories — resolve podcasts/people/companies, search transcripts, list episodes, pull mentions, browse topics, chart rankings, and guests.
Opt-in categories — sponsor analytics, publisher profiles, listener ratings, and corpus-wide bias/brand-suitability views.
`particle_catalog` and `particle_call` — always on, so a default agent can discover and call the rest of the surface.
The selector mechanics and the contract that discovery is free while execution is metered.
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| **Endpoint** | `https://mcp.particle.pro` |
| **Transport** | [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) |
| **Authentication** | OAuth 2.1 (interactive clients) or platform API keys (headless agents) — see [Authentication](/mcp/authentication) |
| **Tool count** | 25 across 12 exposure categories (6 default + always-on `system`, 5 opt-in) |
| **Tool names** | Flat `particle_*` identifiers; every public tool is callable by name |
| **Read/write** | Read-only (every tool advertises `readOnlyHint: true`) |
## How the tools compose
The tools are not isolated lookups — they expose one connected knowledge graph, and two conventions carry most of the design:
* **Lean by default, expand on demand.** Most tools return a minimal payload and opt into richer sections via an `include` array (a company's people, products, and competitors; a person's roles and podcast appearances; an episode's segments, clips, topics, and transcript) or a `mode`/`format` switch. A tool does far more than its name implies — check its input schema (or the `↳` expand hints in [`particle_catalog`](/mcp/tools/system/catalog)) before assuming a capability is missing.
* **Slugs are edges.** Every slug a tool returns — person, company, podcast, episode, publisher, guest — is a valid input to the other tools. Resolve a free-text name once, then traverse: `particle_company_resolve("Andreessen Horowitz")` → `particle_company_get` with `include: ["people"]` → `particle_person_get` with `include: ["podcast_appearances"]` → `particle_podcast_get_episode` with `include: ["transcript", "entities"]`. Four hops from a company name to every entity discussed in an episode one of its partners appeared on.
Connected clients get the same guidance in-band: the server's `initialize` instructions state both conventions on every connect, and `particle_catalog` surfaces each tool's expand options.
## 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. Pass `output_format: "json"` to receive the same response as compact JSON in that block instead. If you need typed JSON with a stable schema for programmatic use, hit the underlying REST endpoint linked from each tool page.
* **Bundling.** Some MCP tools roll up multiple REST calls (e.g. `particle_podcast_get_episode` can also fetch top entities, segments, clips, topics, and the transcript via its `include` array). REST endpoints are single-resource.
* **Identifiers.** MCP tools always accept the agent-facing slug (`person_slug`, `company_slug`, `podcast_slug`, `episode_slug`, `publisher_slug`). The REST API accepts the same slugs alongside encoded canonical IDs.
* **Auth.** Interactive MCP clients use OAuth 2.1 access tokens bound to `https://mcp.particle.pro` as their `aud` claim; headless agents may send the same `pp_*` API keys the REST API accepts. See [Authentication](/mcp/authentication).
* **Errors.** MCP tools surface errors as `isError: true` results with a human-readable message rather than HTTP problem-details bodies. See [Errors](/mcp/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, or the backend behind your frontend — API keys must stay server-side)? 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
Step-by-step setup with troubleshooting for each client.
OAuth 2.1 end-to-end: discovery, registration, PKCE, refresh, revocation.
Every tool, every input, every output.
Exposure categories, the include/exclude selectors, and the always-callable contract.
How tool errors surface and how agents should react.