MCP server reference — SignalRaven Developers

Looking to just connect Claude or ChatGPT? See Connect to Claude / ChatGPT. This page is the technical reference.

Endpoint & transport

URL — https://api.signalraven.ai/mcp
Transport — Streamable HTTP, JSON-RPC 2.0
Auth — OAuth 2.1 (the client discovers the authorization server automatically)

Discovery

Connectors find the authorization server via standard metadata:

api.signalraven.ai/.well-known/oauth-protected-resource (RFC 9728)
auth.signalraven.ai/.well-known/openid-configuration

A 401 from /mcp carries a WWW-Authenticate: Bearer resource_metadata="…" header so clients can auto-discover the flow.

OAuth for connectors

Any MCP client that follows the discovery above can connect with no configuration on our side.

Registration — dynamic client registration (RFC 7591) at api.signalraven.ai/oauth/register, advertised in the metadata. Client ID metadata documents also work.
Scopes — read:signals read:sources read:watchlist read:icp read:intelligence read:usage read:destinations write:intelligence write:destinations. The two write scopes gate the tools that spend credits or change delivery. Registered clients may also request offline_access or its alias offline for a refresh token.
Where scopes are advertised — the 401 challenge’s scope parameter, scopes_supported in the RFC 8414 metadata, and scopes_supported in the OpenID document. Clients differ in which one they read; all three agree.
Consent — the user signs in at signalraven.ai and approves the listed scopes; a member with several workspaces picks one. The token is bound to that workspace.
Sample data — an account without an active workspace completes the same flow and every tool returns clearly labeled sample data, so a connector can be exercised end to end before a workspace exists.
Tool metadata — every tool carries a title, readOnlyHint, destructiveHint, openWorldHint and an outputSchema for its result envelope (mode, data, and total for lists).

Tools

Tool	Scope	Description
list_signals	read:signals	List signals (limit, offset, type, minStrength)
get_signal	read:signals	Fetch one signal by id
list_sources	read:sources	List sources + metrics (period)
get_watchlist	read:watchlist	List watchlist posts
get_icp	read:icp	Get the workspace ICP profile
list_intelligence	read:intelligence	List Account + Person Intelligence reports (limit, offset, type, q)
get_account_intelligence	read:intelligence	Fetch one Account Intelligence report by id
get_person_intelligence	read:intelligence	Fetch one Person Intelligence snapshot by id
get_usage	read:usage	Workspace activity counts
list_destinations	read:destinations	Where signals are delivered, with health
run_account_intelligence	write:intelligence	Start an Account Intelligence run (spends credits)
run_person_intelligence	write:intelligence	Start a Person Intelligence run (spends credits)
create_destination	write:destinations	Create a delivery destination
update_destination	write:destinations	Rename, pause or re-route a destination

Results carry structuredContent.mode = "live" or "sample", mirroring the REST _meta.mode.

Approved vs. sample data

There are two permission layers — worth understanding the difference:

You authorizing a client — “I let this app read my workspace” (OAuth consent, or creating an API key).
SignalRaven approving a client to operate — a platform-level gate for third-party connectors.

Client state	Result
Your own API key	Live data immediately — auto-approved for your workspace
Approved third-party connector	Live data for workspaces users consent to
Pending / unknown connector	Sample data + a prompt to get approved
Denied connector	`403` — no access

So an unknown agent that discovers the server can complete the handshake, see the tool list, and get a realistic taste — but never a real customer’s data — until a human at SignalRaven approves it.

// Example: list_signals tool call (JSON-RPC)
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "list_signals", "arguments": { "limit": 5 } } }