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 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

claude mcp add --transport http particle-pro https://mcp.particle.pro
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.
You’ll need a Particle Pro account with an active project. If you don’t have one, sign up at 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 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: 
Use particle-pro entities/resolve_entity to look up "Marc Andreessen".
Expected response (every tool returns a single markdown text block — verbatim from a live call): 
## Entity matches for "Marc Andreessen" (1)

### Marc Andreessen

**Slug:** marc-andreessen
**Description:** General partner of Andreessen Horowitz
**Wikipedia:** https://en.wikipedia.org/wiki/Marc_Andreessen
The **Slug:** line is what every other tool that takes an entity_slug parameter expects — marc-andreessen here. Feed it into podcasts/get_entity_mentions, podcasts/search_dialogue, podcasts/list_episodes, or podcasts/list_clips. (Company entities additionally get **Ticker:** / **Domain:** lines; people don’t.)

​
A short agent loop

A typical research workflow chains a small number of tools:
  1. Resolve names to slugs — entities/resolve_entity for people, companies/resolve_company for orgs by ticker/domain, podcasts/resolve_podcast for shows.
  2. Discover episodes or dialogue — podcasts/search_dialogue for topic-based ranking, podcasts/get_entity_mentions for “every line about X”, podcasts/list_episodes for filter-driven discovery.
  3. Drill in — podcasts/get_episode with include_full_segments=true and include_transcript=true for the full picture, podcasts/list_clips for engagement-ranked highlight moments.
  4. Pivot to ads — advertising/get_company_ad_presence (“where does company X show up as a sponsor”), advertising/get_podcast_sponsors (“who sponsors podcast Y”), advertising/sponsor_leaderboard (catalog-wide ranking).
Every output is a single markdown text block. Agents read the bolded KV labels (**Slug:**, **Episode slug:**, etc.) to extract identifiers and chain them into the next call.

​
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:<port>/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 from https://platform.particle.pro → Connected Applications and reconnect, picking the correct project at the consent screen.
  • Specific tool errors — see the Errors page for how tool failures surface as MCP isError: true results and how to react to each kind.

​
Next steps

Authentication

OAuth 2.1 end-to-end — useful when wiring up a custom client.

Tool reference

Every input, output, and example for every tool.