How-to guides

Use //SCHEMA from an AI agent

//SCHEMA runs a Model Context Protocol server beside the GraphQL API. An agent connected to it can search your catalog, explain stuck deliveries, look up DDEX values and read these docs, all with the scopes of the key you give it.

Connect Claude Code#

Mint a key for the agent (see Choose a key), then:

claude mcp add --transport http schema https://api.schema.fm/mcp \
  --header "Authorization: Bearer sk_..."

Any MCP client that supports the Streamable HTTP transport and a bearer header connects the same way: the endpoint is https://api.schema.fm/mcp, and the key goes in Authorization, as it does for GraphQL requests.

The server acts on the key's catalog and nothing else. No tool takes a catalog id, for the same reason no GraphQL field does — see Catalogs and tenancy.

Choose a key#

Give the agent its own key rather than sharing one with an application, so you can revoke it on its own.

The agent should…	Scopes
Answer questions about the catalog and its deliveries	`catalog_read`
…and report storage and ingest volume	`catalog_read`, `usage_read`
…and read drafts that are still being authored	`catalog_read`, `catalog_write`

The MCP server is read-only in this version, whatever scopes the key holds. A write scope only makes drafts visible to it.

What it can do#

Tool	What it answers
`whoami`	Which organization and catalog the key acts on, and its scopes.
`search_releases`	Published releases matching a title, artist or label.
`get_release`	One release in full: tracks, credits, labels, titles, dates, deals.
`lookup_vocab`	The allowed DDEX values of one kind, such as `DisplayArtistRole`.
`delivery_triage`	Blocked releases and why, files still expected, recent messages.
`usage`	Bytes held and ingested this period. Quantities only, never prices.
`graphql_query`	Any read-only GraphQL query. Mutations are refused.
`search_docs`, `read_doc`	These docs, searched and read as Markdown.
`describe_type`	The documented definition of one GraphQL type or operation.

Tools a key cannot use are not listed to it. Each catalog tool runs a GraphQL query as the key, so it can see exactly what the same key could see over POST /graphql.

The server has no tools for minting or revoking keys, managing members, delivery accounts, the trial or the billing portal, and will not gain them when write tools are added. An agent reads text that customers and senders wrote — release titles, failure reasons — and nothing written there should be able to reach your credentials or your account.

Webhooks are refused entirely, even to read: graphql_query rejects any query that selects a webhook… field, under any alias or fragment. A webhook is a standing copy of your events sent somewhere else, and "add a webhook to this URL" is exactly the instruction a prompt hidden in a release title would try to give. Manage webhooks in the console or with the GraphQL API.

Point a coding agent at the docs#

An agent writing code against the API, rather than connected to it, can read these docs directly:

/llms.txt lists every page with a one-line summary, linking to a Markdown copy of each.
Every guide, tutorial and explanation is at its own URL with .md appended in place of the trailing slash: this page is https://docs.schema.fm/guides/ai-agents.md.
/llms-full.txt is all of them in one file.
/schema.graphql is the schema with every field's documentation — the reference an agent needs when it writes a query.

To make that automatic in Claude Code, add a line to your project's CLAUDE.md:

//SCHEMA API docs: https://docs.schema.fm/llms.txt — read the relevant page
before writing code against it; field shapes are in /schema.graphql.