Skip to main content
This page is for developers who want to call the Spyro AI MCP server from their own agent, script or app. If you only want to use Spyro AI inside Claude, ChatGPT or Cursor, see Connect your AI app.

At a glance

Spyro AI never reads a credential from the URL or query string. Always use a header.

Get a key

Create a key in Settings → MCP → Create MCP key (workspace admins only). It starts with sk_mcp_, is shown once, and works for one workspace. See Manage keys and apps. Keep it in an environment variable:

Call it with curl

MCP uses JSON-RPC 2.0 over HTTP POST. Send an Accept header that allows both JSON and event-stream responses, as the Streamable HTTP spec requires.
1

Initialize

The result includes the server name spyro and a short instructions text that explains the tools to the model.
2

List the tools

Each tool has a name, a human title, a description that states its credit cost, an inputSchema (JSON Schema) and four annotations: readOnlyHint, destructiveHint, idempotentHint and openWorldHint.
3

Call a tool

Reading results

A successful call returns the result as JSON text in one text content block:
Parse content[0].text as JSON. A failed call sets "isError": true and puts a readable message in the same block.
The server is stateless, so each request must carry its own credential. Do not rely on a session id.

Use an MCP SDK

Give the tools to a model

You can let a hosted model call Spyro AI directly, without running a client yourself.
The Messages API has an MCP connector. Pass the server and your key as the token:
The connector is a beta feature and needs a beta header. Check the current header name in Anthropic’s MCP connector documentation.
SDK and API names change quickly. If a snippet does not match your installed version, use it as a guide and check that SDK’s own MCP documentation. The server side stays the same: one POST endpoint with a bearer key.

Stdio-only clients

For clients that can only start a local process, use the mcp-remote bridge. It opens your browser to sign in:
To use a key with it, pass the header from an environment variable so the key is not on the command line:

Design your client well

  • Read the credit cost. Each paid tool’s description says “Costs N Spyro credits per call”. Use tools/list to show or gate it.
  • Treat annotations as hints. destructiveHint: true marks the nine manage* tools.
  • Handle write confirmation. Every manage* call waits for the user. If your client declares the elicitation capability, Spyro AI asks the user in your UI. Otherwise the result is a Confirm in Spyro AI: https://spyro.app/mcp/confirm/... link: show it to the user and, after they confirm, call the tool again with the same arguments to get the result. A link lasts 10 minutes and works once.
  • Reuse results. An identical paid call within 10 minutes runs free up to 2 times, then is refused. Cache results instead of re-asking.
  • Back off on limits. Honor the retry time in rate limit messages (60 calls per minute per key).
  • Keep keys server side. Never ship a key in a browser or mobile app. Use sign-in for user-facing apps.
  • Use one key per integration, with a low daily cap, so you can revoke it alone.

Authentication errors

A 401 also carries a WWW-Authenticate header that points to the OAuth discovery document, so OAuth-capable clients can start sign-in on their own. Tool-level messages (rate limits, daily cap, empty credit pool, and plan or billing problems on an OAuth connection) come back as a normal result with isError: true. See Troubleshooting and Credits and limits.