> ## 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.
# Quickstart
> Connect the Particle Pro MCP server to Claude Code, Claude Desktop, Cursor, VS Code, ChatGPT, Windsurf, Zed, an LLM API, or a custom MCP client.
The Particle Pro MCP server runs at **`https://mcp.particle.pro`** over Streamable HTTP. Point any modern MCP client at the URL and the client handles the OAuth handshake automatically.
## Install
**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) — both encode the same config as the manual tabs below, so use whichever you prefer.
```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 does not accept a bare
// `url` for remote MCP servers — only stdio `command`/`args` entries.
// 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"
}
}
}
```
```json Windsurf theme={"dark"}
// ~/.codeium/windsurf/mcp_config.json — note Windsurf uses `serverUrl`,
// not `url`. UI alternative: Windsurf Settings → Cascade → MCP Servers.
{
"mcpServers": {
"particle": {
"serverUrl": "https://mcp.particle.pro"
}
}
}
```
```json Zed theme={"dark"}
// settings.json — Zed prompts for the OAuth flow on first use when no
// Authorization header is configured.
{
"context_servers": {
"particle": {
"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
```
**Agent-assisted setup:** in any coding agent that can edit files (Claude Code, Cursor), you can skip the manual config entirely — paste:
```text theme={"dark"}
Add the Particle Pro MCP server to this client's MCP configuration. It is a
remote Streamable HTTP server at https://mcp.particle.pro using OAuth (no
command/args, no API key in the config). Find this client's MCP config file,
add it under the name "particle", and tell me how to trigger the OAuth
approval.
```
**Claude Desktop alternative — UI flow:** 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 entirely.
### ChatGPT
ChatGPT connects through its connector UI rather than a config file (requires a Pro, Plus, Business, Enterprise, or Edu plan):
1. Open **Settings → Apps → Advanced settings** and enable **Developer mode**.
2. Back in **Settings → Apps**, choose **Create app** and enter `https://mcp.particle.pro` as the MCP server URL, with **OAuth** as the authentication method.
3. Complete the OAuth approval in the browser pop-up, picking the project the agent should act on.
4. In a conversation, enable the connector from the composer's tools menu, then run the [sanity check](#sanity-check) below.
See [OpenAI's developer-mode guide](https://platform.openai.com/docs/guides/developer-mode) for connector specifics on their side.
### Calling it from an LLM API
Server-side agents can hand the MCP server straight to a model API — no MCP client library needed. Both providers connect to `https://mcp.particle.pro` themselves; authenticate with a [project API key](/mcp/authentication#api-keys-for-headless-agents) as the bearer:
```bash Anthropic Messages API theme={"dark"}
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
-d '{
"model": "claude-opus-4-8",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Which podcasts discussed Anthropic this week?"}],
"mcp_servers": [{
"type": "url",
"url": "https://mcp.particle.pro",
"name": "particle",
"authorization_token": "'$PARTICLE_API_KEY'"
}],
"tools": [{"type": "mcp_toolset", "mcp_server_name": "particle"}]
}'
```
```bash OpenAI Responses API theme={"dark"}
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-5.5",
"tools": [{
"type": "mcp",
"server_label": "particle",
"server_url": "https://mcp.particle.pro",
"authorization": "'$PARTICLE_API_KEY'",
"require_approval": "never"
}],
"input": "Which podcasts discussed Anthropic this week?"
}'
```
Every tool is read-only (`require_approval: "never"` is safe here); calls meter to the project that owns the key exactly like any other MCP traffic.
### Any other client
Point the client at `https://mcp.particle.pro` over Streamable HTTP and prefer OAuth when the client supports it. Stdio-only clients bridge through `mcp-remote` (tab above). Headless or programmatic callers should read [Authentication](/mcp/authentication).
You'll need a Particle Pro account with an active project. If you don't have one, [sign up at platform.particle.pro](https://platform.particle.pro) first.
## OAuth flow
The first tool call triggers an OAuth flow:
1. Your client opens `https://api.particle.pro/oauth/authorize?...` in a browser.
2. You sign in to Particle Pro (if not already), then approve the requested scopes (`mcp:read`, `mcp:write` by default) and pick which project the agent should act on.
3. The browser redirects back to your client's local callback. The client exchanges the authorization code for tokens, stores them, and re-issues the original tool call.
Subsequent calls reuse the cached tokens. Refresh happens automatically — see [Authentication](/mcp/authentication) for the full flow and the dynamic-client-registration details.
## Sanity check
Once connected, ask the agent to call a low-cost read tool. A good first call:
```text theme={"dark"}
Use particle particle_entity_resolve to look up "Marc Andreessen".
```
Expected response (every tool returns a single markdown text block; pass `output_format: "json"` to receive the structured JSON form instead):
```markdown theme={"dark"}
## Entity matches for "Marc Andreessen" (1)
### Marc Andreessen
- **Type:** person
- **Person slug:** marc-andreessen
- **Title:** General Partner
- **Company:** Andreessen Horowitz
- **Wikipedia:** https://en.wikipedia.org/wiki/Marc_Andreessen
```
The handle row — `- **Person slug:**` for a person — is what every `person_slug` parameter expects (`marc-andreessen` here). Feed it into `particle_podcast_find_mentions`, `particle_podcast_search_transcripts`, or `particle_podcast_list_episodes`. (Company results lead with `- **Type:** company` and a `- **Company slug:**` row plus `- **Ticker:**` / `- **Domain:**`.)
## A short agent loop
A typical research workflow chains a small number of tools:
1. **Resolve names to slugs** — `particle_entity_resolve` for any named thing (returns a typed handle), `particle_person_resolve` for people only, `particle_company_resolve` for orgs by ticker/domain, `particle_podcast_resolve` for shows.
2. **Discover episodes or dialogue** — `particle_podcast_search_transcripts` for topic-based ranking (relevant clips arrive inline), `particle_podcast_find_mentions` for "every line about X", `particle_podcast_list_episodes` for filter-driven discovery.
3. **Drill in** — `particle_podcast_get_episode` with `include: ["segments", "clips", "transcript"]` for the full picture.
4. **Pivot to ads, rankings, and brand safety** — opt-in categories like `particle_company_get_podcast_ad_presence` ("where does company X advertise"), `particle_podcast_get_rankings` (chart movers/history), and `particle_podcast_get_suitability_leaderboard` (safest publishers). These are callable by name even when not advertised — see [Tool sets & discovery](/mcp/tool-sets).
Every output is a single markdown text block. Agents read the bolded KV labels to extract identifiers and chain them into the next call. Two shapes appear: top-level summary lines under `## Heading` use flat `**Key:** value`, while per-item field rows under `### Item title` use `- **Key:** value` bullets. Either way, the bold-key prefix (e.g. `**Slug:**`, `**Episode slug:**`) is what to grep for.
## Troubleshooting
* **"server requires authentication"** — your client hit the MCP endpoint without a bearer token, or the token failed verification. Re-run the OAuth flow; if you persist tokens to disk, delete the cache for `mcp.particle.pro`.
* **Browser callback hangs** — confirm the client's `redirect_uri` matches one it registered. Most desktop MCP clients use `http://localhost:/callback`; the AS allows localhost redirects without prior approval.
* **403 on a tool call after a successful connection** — the OAuth grant is for the wrong project. Revoke the connection ([Manage connections](/mcp/authentication#manage-connections)) and reconnect, picking the correct project at the consent screen.
* **Specific tool errors** — see the [Errors](/mcp/errors) page for how tool failures surface as MCP `isError: true` results and how to react to each kind.
## Next steps
OAuth 2.1 end-to-end — useful when wiring up a custom client.
Every input, output, and example for every tool.
Default vs opt-in categories, the include/exclude selectors, and the meta-tools.