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 withsk_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 HTTPPOST. Send an Accept header that allows both JSON and event-stream responses, as the Streamable HTTP spec requires.
1
Initialize
spyro and a short instructions text that explains the tools to the model.2
List the tools
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 onetext content block:
content[0].text as JSON. A failed call sets "isError": true and puts a readable message in the same block.
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.- Anthropic API
- OpenAI Responses API
- Vercel AI SDK
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 themcp-remote bridge. It opens your browser to sign in:
Design your client well
- Read the credit cost. Each paid tool’s description says “Costs N Spyro credits per call”. Use
tools/listto show or gate it. - Treat annotations as hints.
destructiveHint: truemarks the ninemanage*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 aConfirm 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.
