@haddowg/json-api-mcp
Part of the jsonapi.rest suite — a complete, spec-compliant JSON:API 1.1 stack: a framework-agnostic PHP core, a Symfony bundle, a Laravel package, and the typed TypeScript client, bound together by one conformance-tested OpenAPI 3.1 contract. Full documentation: haddowg.github.io/json-api-ts.
MCP tool definitions and a call handler for a haddowg/json-api server. A build-time
generator turns the server's OpenAPI document into one JSON model, which you commit; the
runtime serves one tool per collection, resource, related and custom action operation from it,
with input schemas valid under OpenAI's and Anthropic's strict modes. Calls run through
@haddowg/json-api-client. The package doesn't own an MCP server: the host lists
the tools and passes calls to the handler.
Install
npm install @haddowg/json-api-mcp @haddowg/json-api-client
npm install --save-dev @haddowg/json-api-codegen
Generate the model
npx @haddowg/json-api-mcp --input openapi/v5.json --output src/mcp/v5.mcp.json
npx @haddowg/json-api-mcp --input openapi/v5.json --output src/mcp/v5.mcp.json --check # in CI
The model is generated, and its leading $comment says so. Regenerate it rather than editing
it by hand.
Tools include one relationship deep by default, so each tool's schema carries only the types its
direct relations reach. Pass --include-depth <n>, or all for every path the document
declares, to change that.
An operation can drop or reshape its tool with the x-mcp vendor extension. false leaves
its tool out of the model, and an object of name, title and description replaces those
parts of the tool.
A deprecated operation's tool description starts with Deprecated., an x-mcp description
included, and so does the description of each deprecated attribute, relationship, filter and
sort key in a tool's input.
Serve it
The runtime loads from ESM or CommonJS and needs only the client.
const { createJsonApiMcp } = require('@haddowg/json-api-mcp')
const mcp = createJsonApiMcp({ model: require('./mcp/v5.mcp.json') })
const session = await mcp.forRequest({ grantedScopes: token.scopes, context: { token } })
session.tools // answer tools/list with these
await session.callTool('albums_list', { sort: ['-releasedAt'], pageSize: 5 })
Every result's structuredContent is a JSON:API-like envelope. A single resource comes back as
{ data }, a collection as { data, links, meta } with only the pagination links, a delete as
{ data: null } and a meta-only action as { meta }. A flattened resource keeps the links its
type names, such as a presigned upload URL, under links.
Coming from 1.2: a get returns { data } where it returned { item }, a create or update is
wrapped in { data } instead of coming back bare, and a collection lists its resources under
data instead of items. A delete returns { data: null } instead of a line of text, a
meta-only action { meta } instead of the bare meta object, and a URL action
{ data: { url, type, expiresAt? } } instead of the bare object. Regenerate the model to get the
new shapes. A model generated by 1.2 still loads and keeps the 1.2 shapes its output schemas
describe. The migration notes
cover the rest.
Scope filtering counts only the security requirements a caller can meet with its credential
schemes, the document's oauth2 schemes unless you pass credentialSchemes. Scopes, feature
gates, headers and error hints come from optional hooks: scopeMatcher, capabilities,
includeOperation, decorateTool, requestInit and mapError. See the
MCP tools guide.