mcp-service-registry 0.3.0

Multi-tenant MCP server that shares microservice API contracts between AI coding assistants

mcp-service-registry

An MCP server that lets multiple AI coding assistants (Claude Code, Cursor, etc.) share microservice API contracts. A developer working on one service can look up another service's real endpoints and field names — instead of guessing and creating mismatched integrations.

Example: "Billing" needs to call "Inventory". Instead of inventing field names, Billing's AI asks the registry and gets the exact Stock Request contract (itemId, quantity, warehouseId, requestedBy).

---

Which user are you?

I want to...	Do this
Look up other services' APIs (most people)	Connect to a running registry — just a URL, no install
Run my own registry (host it)	Self-host — install + database

---

A. Connect to a running registry (no install)

If your team already has a registry running (for example on Render), you only need its URL. Nothing to install.

Claude Code:

claude mcp add --transport http registry https://YOUR-REGISTRY-URL/mcp

Or add it manually to your MCP config:

{
  "mcpServers": {
    "registry": {
      "type": "http",
      "url": "https://YOUR-REGISTRY-URL/mcp"
    }
  }
}

Then just ask your assistant, for example:

• "Using the registry, what services exist?"
• "What fields does the inventory stock-request API need?"
• "Register this service's API in the registry."

That's it — the assistant will call the tools automatically.

---

B. Run your own registry

1. Install

pip install mcp-service-registry
# or, to run without installing permanently:
uvx mcp-service-registry

2. Provide a PostgreSQL database

The server needs a PostgreSQL database. Point it at one with the REGISTRY_DB_URL environment variable:

export REGISTRY_DB_URL="postgresql://user:pass@host:5432/dbname"

Create the table once:

CREATE TABLE IF NOT EXISTS services (
  name        TEXT PRIMARY KEY,
  description TEXT NOT NULL,
  contract    JSONB NOT NULL,
  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

Tip: a free cloud PostgreSQL (e.g. Neon) works well. On Windows + local Docker, use 127.0.0.1 instead of localhost in the URL.

3. Run it

Local mode (stdio) — for a single machine / testing / the Inspector:

mcp-registry

Add it to Claude Code as a local command:

{
  "mcpServers": {
    "registry": {
      "command": "mcp-registry",
      "env": { "REGISTRY_DB_URL": "postgresql://..." }
    }
  }
}

Network mode (HTTP) — to share it with other devices:

export MCP_TRANSPORT=http
export MCP_PORT=8000          # optional; cloud hosts set PORT automatically
mcp-registry

It serves at http://<this-machine>:8000/mcp, with a health check at /health.

---

The tools

Tool	What it does	Arguments
list_services	List all registered services + descriptions	none
get_service_api	Get one service's endpoints, request fields, response fields	service
add_service	Add or update a service's API contract	name, description, endpoints_json

Registering a service

add_service takes the service name, a one-line description, and a JSON array of endpoints. Each endpoint looks like:

[
  {
    "method": "POST",
    "path": "/stock-request",
    "summary": "Create a stock request",
    "request_fields": {
      "itemId": "string (required)",
      "quantity": "integer (required, > 0)",
      "warehouseId": "string (required)",
      "requestedBy": "string (required)"
    },
    "response_fields": {
      "requestId": "string",
      "status": "string (PENDING | APPROVED | REJECTED)"
    }
  }
]

The easiest way to register: just ask your AI assistant, e.g. "Register the inventory service in the registry with a POST /stock-request endpoint that takes itemId, quantity, warehouseId, requestedBy." — it will call add_service for you.

---

Testing locally with the MCP Inspector

uvx --with mcp-service-registry mcp dev -c "from service_registry.server import mcp"

(Or clone the repo and run uv run mcp dev src/service_registry/server.py.)

---

Configuration reference

Variable	Default	Meaning
REGISTRY_DB_URL	local Docker URL	PostgreSQL connection string
MCP_TRANSPORT	stdio	stdio (local) or http (network)
MCP_PORT / PORT	8000	Port for HTTP mode

---

Works with other assistants

Because it uses the open Model Context Protocol, it isn't limited to Claude Code — any MCP-compatible client (Cursor, and others) can connect the same way.

License

MIT