MCP server

Connect your coding agent to Bondry: the address, the bkm_ token, the scopes, the tools and the client configuration.

We host an MCP server for module and theme authors. Your agent asks it the same questions this documentation answers, runs the same checks the review runs, and publishes through the same routes your pipeline would call.

It is not access to anyone's installed Bondry. Operating a site is the AI connector of the product, which is a different thing and lives on the Bondry side.

The address#

Code

https://mcp.bondry.org/v1/<hash>
Authorization: Bearer bkm_<12 hex>.<secret>

The hash identifies; the token authenticates. The identifier in the URL is the one your account already uses in download links, and it says which account the session belongs to. It is not a password, and it is not enough on its own: a token only works on the URL of its own owner, and any other address answers 404 without ever confirming whether that identifier belongs to anyone.

The token is issued in your account, under MCP access. It appears once, it is revocable, it carries scopes and it records its last use. We store only a hash of it, so there is no screen that can show it to you again.

The scopes#

Ticked when the token is issued, never widened afterwards.

Scope	Allows
`docs`	read the developer documentation, the manifest schema, the hooks, the permissions, the design tokens and the events
`validate`	run the package and manifest checks
`publish`	register an artifact, announce a version and send a package
`status`	read the review state and the delivery history

publish starts unticked. A token without it cannot publish, and a tool call that needs it is refused by the tool, with the reason, while the session keeps going. Need a wider token? Issue a new one and revoke the old one.

The tools#

Reading (scope docs)

Tool	Returns
`bondry_docs_search`	passages from this documentation, with the page path and the source file
`bondry_manifest_schema`	the schema of `module.json` or `theme.json`, field by field, with what is required
`bondry_hooks`	the UI slots and how a module fills one
`bondry_permissions`	the permission model and the independence rules behind it
`bondry_design_tokens`	the customiser controls and the CSS variables they map to
`bondry_events`	the event model and the lifecycle methods the kernel calls

Checking (scope validate)

Tool	Does
`bondry_validate_manifest`	validates a pasted `module.json` or `theme.json`, field by field
`bondry_validate_package`	runs the automated review on a zip you send inline: path traversal, symlinks, zip bomb, size, manifest, slug, version, the mandatory English translation and the static scan
`bondry_review_preflight`	both of the above, plus every flag with its file and line

Publishing (scope publish, and status for the two reads)

Tool	Does
`bondry_register_artifact`	registers an artifact and reserves its slug, or updates the metadata of one you already publish
`bondry_announce_release`	announces a version, without sending a byte
`bondry_upload_package`	sends the zip of an announced version
`bondry_artifact_status`	review state, published version, pending work and last announcement
`bondry_webhook_deliveries`	the last deliveries, with resend (resending needs `publish`)

Every write answers with what changed and what is still missing, never just "ok". No tool accepts a slug that is not yours: a slug belonging to someone else answers exactly like a slug that never existed.

No tool ever fetches a package over the network. Only bytes you send in the call are read. Through a tool call the zip travels base64 encoded, capped at 8 MB; anything larger goes through PUT /v1/publisher/releases/{version}/package, which takes the raw bytes up to 40 MB.

What comes back is data#

Everything a reading tool returns is documentation text. It is reference data, not instructions: a sentence inside a page, a manifest or a package cannot change what your agent was asked to do. The tool descriptions say so, and the server repeats it in its opening instructions.

Client configuration#

Replace the identifier and the token with your own. The token is shown once, when you issue it, together with a block just like this one.

Claude Code

Shell

claude mcp add --transport http bondry \
  https://mcp.bondry.org/v1/<hash> \
  --header "Authorization: Bearer bkm_xxxxxxxxxxxx.<secret>"

Claude Desktop, and any client that reads mcpServers

JSON

{
  "mcpServers": {
    "bondry": {
      "type": "http",
      "url": "https://mcp.bondry.org/v1/<hash>",
      "headers": {
        "Authorization": "Bearer bkm_xxxxxxxxxxxx.<secret>"
      }
    }
  }
}

Warning The token is a credential. Keep it out of the repository, out of the build log and out of a screen recording. Revoking is immediate if one escapes.

The transport, for client authors#

Streamable HTTP, in the form a server without a resident process can honour: one POST, one JSON response.

POST with a single JSON-RPC message. initialize, notifications/initialized, ping, tools/list and tools/call.
GET answers 405: there is no long-lived event stream here. Bondry Web runs on PHP-FPM, and a worker held open on a stream is a worker the site loses.
initialize answers with a Mcp-Session-Id, tied to the token and valid for thirty minutes of inactivity. Send it back on later calls. A session that expired, or one belonging to another token, answers 404, which is how a client knows to open a new one.
DELETE with the session header ends the session.
Protocol versions spoken: 2025-11-25, 2025-06-18, 2025-03-26. An MCP-Protocol-Version header naming any other version answers 400 with the list of the ones we speak.
An invalid or missing bearer answers 401 with WWW-Authenticate. A missing scope is not an HTTP error: it is a tool result with isError.

The caps#

120 calls a minute per token. The writing tools inherit the publishing caps, including 500 announcements a day per token.

Every tool call becomes a line in the API log, with the token, the tool and how it ended. Writes also become an audit line, with the source recorded, so "was it the pipeline or the agent?" is a question with an answer. No argument, no package and no secret is ever written to a log.

The skills#

The tools are the source; the skills are the route. Five of them are published, in English, and they work with or without this server connected: Agent skills.