// MCP SERVER

Connect your coding agent
to your catalog

The microservice.md MCP server lets Claude Code, Cursor and other agents read your services before they change code: the service's MICROSERVICE.md, its contracts, its neighbours' contracts, and who consumes or depends on what.

Server URL: https://mcp.microservice.md/mcp

Step 1

Add the server to your agent

You need a microservice.md account with at least one saved service. Create one free if you don't have one yet.

Claude Code

Run this in your terminal:

claude mcp add --transport http microservice-md https://mcp.microservice.md/mcp

Then start Claude Code, run /mcp, pick microservice-md and choose Authenticate. Your browser opens on the microservice.md sign-in page. Once you approve, the tools are available in every session.

Cursor

Add the server to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "microservice-md": {
      "url": "https://mcp.microservice.md/mcp"
    }
  }
}

Cursor then asks you to log in to the server from its MCP settings, which opens the same sign-in page.

Other clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth can connect. Point it at the server URL above. Clients register themselves, so there's no client ID to copy.

Step 2

Link your repo to its service

Put the service's MICROSERVICE.md at the root of its repo, with a **Catalog ID:** line. The agent reads that line and knows which catalog service it's working on, without being told.

Files you download from microservice.md already have the line. You can also copy it from the service's Overview page. Without it, the agent calls list_services and asks you which service you mean.

# payment-microservice
> Processes charges and manages the payment lifecycle.

**Team:** payments-team
**Catalog ID:** 9b2f6c1e-3a47-4d8e-b5f0-7c1d2e3a4b5c

Step 3

Ask before you change code

You don't call tools by name. Ask in plain words and the agent picks the tool. Here's what each one does, with a prompt that uses it.

list_services

Lists the services in your catalog with ID, name, mission, team and saved version, and flags unsaved draft changes.

“Which services are in my microservice.md catalog?”

get_service_md

Returns a service's MICROSERVICE.md from its last saved version, or from a version you name.

“Read the MICROSERVICE.md for this repo and summarize what the service owns.”

list_artifacts

Lists the files generated for a service: OpenAPI, AsyncAPI, proto, GraphQL, runbook, ADRs, C4 and the context pack.

“Which contracts does microservice.md generate for this service?”

get_artifact

Gets one generated file. Use it for this service's contracts, and for a dependency's contracts before writing code that calls it.

“Fetch payment-microservice's openapi.yaml and write a client for POST /payments.”

find_event_consumers

Finds which services publish and which consume an event, with team and contact for each.

“Who consumes UserRegistered? I want to add a field to it.”

find_dependents

Finds the services that depend on a service, synchronously (with the endpoints they call, when recorded) or through events.

“What depends on payment-microservice before I change GET /payments/{id}?”

Prompts

The server also offers two ready-made prompts. In Claude Code they appear as slash commands, for example /mcp__microservice-md__impact_check.

start_from_serviceImplement a service from its MICROSERVICE.md: the agent reads the file, the service's contracts and its dependencies' contracts, then proposes a plan before writing code.
impact_checkDescribe a change you plan to make. The agent checks every dependent and every consumer of the events it touches, summarizes who is affected, and asks before going ahead.

Use it from CI and scripts

Pipelines can't do a browser sign-in, so they use an API key. Create one in Settings → API keys, store it as a CI secret, and send it as a bearer token. Treat it like a password, and revoke it in Settings if it leaks.

The server is stateless, so a script can send a single tools/call with no handshake first:

curl -s https://mcp.microservice.md/mcp \
  -H "authorization: Bearer $MICROSERVICE_MD_API_KEY" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_services","arguments":{}}}'

The reply is one JSON-RPC response. The services are in result.structuredContent.services. A revoked or invalid key gets HTTP 401.

What this first version does

Read-only.

Agents can read your catalog, not change it. Edits to a MICROSERVICE.md still go through microservice.md.

Saved versions only.

Answers come from the last saved version of each service. When a service has unsaved edits, the answer says so and the agent tells you.

Your own catalog.

The server sees the services you own. Services other people share with you are not included yet.

Account required.

Every call is signed in: OAuth for coding agents, an API key for CI. There is no anonymous access.

Writing back to the catalog is next. See the roadmap.

No services in your catalog yet?

Document your first one with the wizard. Free during beta.

→ Get started freeWhat is MICROSERVICE.md?