# microservice.md

> microservice.md is a free MCP server for developer tools. Coding agents read service docs, contracts and dependents from a microservice.md catalog. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** API, Web
- **Website:** https://microservice.md/docs/mcp
- **MCP Registry name:** md.microservice/catalog
- **Categories:** developer tools
- **Listing updated:** 2026-11-15

## About

The server is built for one habit: look before you edit. Before touching an event or endpoint, an agent can ask who consumes it, with team and contact for each publisher and subscriber, or which services depend on a service, either synchronously with the endpoints they call when recorded, or through events. It can also fetch a neighbour's generated contract, such as OpenAPI, AsyncAPI, proto, GraphQL, runbook, ADRs and C4 files, before writing code that calls it.

A repo links itself to the catalog through a Catalog ID line in the MICROSERVICE.md at its root, so the agent knows which service it is working on. Without it, the agent lists services and asks. Two ready-made prompts are included, one of them an impact check that shows as a slash command in Claude Code.

This first version is read-only, answers only from the last saved version of each service and says when unsaved edits exist, and covers only services you own. Every call is authenticated: OAuth for coding agents and an API key for CI, with agents you can disconnect from Settings. The server is stateless, so a script can send a single tools/call.

## Features

- **Catalog listing:** Lists services with ID, name, mission, team and saved version.
- **Service document:** Reads a service's MICROSERVICE.md from a saved version.
- **Generated contracts:** Fetches OpenAPI, AsyncAPI, proto, GraphQL, runbook, ADRs and C4 files.
- **Event consumer lookup:** Shows who publishes and consumes an event, with team contact.
- **Dependent lookup:** Finds services that depend on another, directly or via events.
- **CI access:** API keys let pipelines call the server without a browser sign-in.

## Good for

- Check who consumes an event before adding a field to it
- See what depends on an endpoint before changing it
- Generate a client from a neighbour service's OpenAPI file
- Have an agent summarise what a service owns before editing it
- Script catalog queries from a CI pipeline

## Install

### Claude Code (Terminal)

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

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://mcp.microservice.md/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "catalog": {
      "url": "https://mcp.microservice.md/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "catalog": {
      "type": "http",
      "url": "https://mcp.microservice.md/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "catalog": {
      "serverUrl": "https://mcp.microservice.md/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "catalog": {
      "type": "http",
      "url": "https://mcp.microservice.md/mcp"
    }
  }
}
```

## Tools

- `list_services`: Lists catalog services with ID, name, mission, team and saved version.
- `get_service_md`: Returns a service's MICROSERVICE.md from a saved version.
- `list_artifacts`: Lists generated files such as OpenAPI, AsyncAPI, proto, GraphQL, runbook, ADRs and C4.
- `get_artifact`: Gets one generated file for a service or its dependency.
- `find_event_consumers`: Finds publishers and consumers of an event with team and contact.
- `find_dependents`: Finds services that depend on a service, synchronously or through events.

## FAQ

### Do I need an account?

Yes. You need a microservice.md account with at least one saved service; there is no anonymous access.

### Can the agent change the catalog?

No. This version is read-only; edits go through microservice.md.

### How does the agent know which service a repo is?

Through the Catalog ID line in the MICROSERVICE.md at the repo root.

### Does it see services shared with me?

Not yet; it covers services you own.

### How do I add it to Claude Code?

Run claude mcp add --transport http microservice-md https://mcp.microservice.md/mcp, then authenticate from /mcp.

### Is microservice.md free?

Yes. microservice.md is free to use.

### How do I add microservice.md to Claude Code?

Run this command in your terminal: claude mcp add --transport http catalog https://mcp.microservice.md/mcp

### What are the best alternatives to microservice.md?

The closest alternatives to microservice.md are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/microservice-md
