MCP Tools as API Contracts: Document What Your Agents Can Do
A few months ago we shipped API Contracts: OpenAPI, gRPC, GraphQL and AsyncAPI specs, linked directly to the C4 elements that implement and consume them. The idea was simple — the precise, machine-readable description of an interface belongs inside your architecture, not in a Notion page nobody updates.
There was one interface we hadn't covered. The newest one. The one your services increasingly expose not to other services, but to AI agents: MCP.
An MCP server publishes a set of tools — each with a name, a description, and a JSON Schema for its inputs. That's a contract. It's the contract that decides what an agent is allowed to do to your system. And until today, it was completely invisible in your architecture documentation.
Not anymore. MCP is now a first-class API contract type in Archyl — the fifth, alongside HTTP, gRPC, GraphQL and AsyncAPI.
The hard part: MCP tools don't live in a file
The other four contract types share an assumption — there's a spec file in a repo. openapi.yaml. schema.graphql. You point Archyl at it and we render it.
MCP breaks that. An MCP server's tools are defined in code, and the complete, authoritative list only exists at runtime, when a client calls tools/list and gets back the schema for every tool. There's no universal mcp.yaml to point at.
So we built two ways in.
Two ways to add an MCP contract
Paste it. If you already have your tools/list output, paste it. Archyl validates it and renders every tool — its description, and its input parameters as a readable table.
Or just give us the URL. Tell Archyl where your MCP server lives, optionally add an access token (as a header or a query parameter), and click Discover tools. Archyl connects, runs the handshake, and pulls in every tool and parameter automatically. No copy-paste, no hand-maintained file.
How live discovery works — and why it's safe
The discovery happens in your browser, not on our servers. When you click Discover tools, your browser talks to your MCP server directly.
That choice matters:
- Your token never leaves your browser. Archyl stores the discovered tools and the connection details — the URL, the transport, where the token goes — but never the token itself.
- No server-side reach into your network. Because the call originates from your machine, there's no way for it to be pointed at someone else's internal services. The whole class of server-side request forgery risk simply doesn't exist here.
- It reaches localhost and private servers. Testing a server running on your laptop or inside your network? It works, because your browser can see it.
The one trade-off is CORS: a third-party server has to allow Archyl's origin for your browser to read the response. For servers you control that's a one-line config; for the rest, the paste option is always there.
Linked to your architecture, like every other contract
Once it's in, an MCP contract behaves like any other. Link it to the container or component that hosts the server. Browse every tool and its input schema. Re-discover it when the server changes. It shows up next to your REST and GraphQL contracts, because to the agents calling it, it's just as real an API.
This turns your MCP contract into something genuinely new: a map of what your AI agents are allowed to do to a given part of your system — documented, linked, and reviewable.
We use it on ourselves
Archyl is itself an MCP server — 178 tools that let you drive your architecture from Claude Code, Cursor, or any MCP client. The first MCP contract we created was our own: point Archyl at its own endpoint, discover all 178 tools, link it to the platform. Our agent surface now documents itself.
Try it
Open any project, go to API Contracts, create a new one, and pick MCP. Paste your tools/list, or drop in a URL and hit Discover tools.
Your services already talk to agents. Now your architecture knows what they're saying.