This page is for readers who want the mechanics. To simply get the server running, see
the overview and the guide for your client.
run parameters
Typical flow
list_services with platform: "linkedin" to see what LinkedIn data is available,
in what shape, at what price.run with service: "linkedin/profile.info" and
inputs: ["https://www.linkedin.com/in/..."].- Read
served_by in the result to know which offer answered.
How it works
The server is a thin, stateless wrapper over the API, built around
services of the form <platform>/<service> (e.g.
linkedin/profile.info, reddit/subreddit.posts). The agent discovers what exists with
list_services, then calls run with the chosen service and its inputs. The catalogue
gives it everything needed to pick: the input kind (URLs or free-text queries), the
accepted URL shapes with concrete examples, the typed options, and the
offers behind the service with their price per record and batch cap.
It comes from GET /v1/services, and nothing is hardcoded in the server.
Which offer serves a run is the router’s call: it walks the failover chain and the
response’s served_by says which one answered. The agent can pin one with provider,
but pinning disables failover, so omitting it is the better default.
The server checks every call against the live catalogue before it sends the request:
- the
service parameter is an enum of the services live at startup, so the agent
cannot invent one
- at call time it re-checks the service against the refreshed catalogue (5-minute
cache), the batch size against the relevant cap (the pinned offer’s, or the largest in
the chain), and a pinned offer against those that actually serve the service
- a validation failure returns a corrective error listing the valid alternatives, rather
than a bare API error.
The server fetches the catalogue when it starts, then refreshes it lazily. If it cannot
load it at all, it refuses to serve — an unreachable catalogue means the API itself is
unreachable, so every tool would fail anyway. If a later refresh fails, it keeps serving
the last known catalogue.
run and get_extraction wrap their records in an explicit untrusted-content notice.
Scraped bios, comments and display names are third-party text that could carry
prompt-injection payloads, so the agent treats them as data to report on, never as
instructions.
Authentication
The hosted endpoint at https://mcp.socialrouter.io/mcp takes a bearer token on every
request. Most clients get one by signing you in, and the rest send an API key:
It is stateless and holds no credential of its own, so there is no session to keep and
every call is billed to the account that made it. Authentication
covers both forms.
The local server (Claude Desktop, offline work) reads the same
key from its environment instead:
Calling it by hand
Useful to confirm a key works before touching any client config:
A response containing "serverInfo" means the key and the network are both fine. A
401 means the key is wrong, revoked, or missing from the header. 
