Skip to main content

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

Metadata

Release files for mcp-service-registry 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-service-registry 0.3.0
File Size Uploaded Provenance Actions
mcp_service_registry-0.3.0.tar.gz 71.2 kB Without provenance Details for mcp_service_registry-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-service-registry 0.3.0
File Interpreter ABI Platform Actions
mcp_service_registry-0.3.0-py3-none-any.whl Python 3 none any Details for mcp_service_registry-0.3.0-py3-none-any.whl

Total release size: 80.0 kB

Release files / mcp_service_registry-0.3.0.tar.gz

Download URL mcp_service_registry-0.3.0.tar.gz
Size 71.2 kB
Tags Source
SHA-256 checksum
How to use checksums
1da067362c71b7325c34c4818ea1a0d4be8017892137945d59be732d3d45f61a
BLAKE2b-256 checksum
How to use checksums
381d5aa59357e6f4b3612cbb27c50d96df46989104d06c7be63c433a7c232df3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / mcp_service_registry-0.3.0-py3-none-any.whl

Download URL mcp_service_registry-0.3.0-py3-none-any.whl
Size 8.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c1edc5bf24e735d0905985f06c91e6891454a4d374c783c71a9d2fe3cc686f4f
BLAKE2b-256 checksum
How to use checksums
4a068693e648f898dbe2f6b2eea425e7ee1198ba36f98b10e54f7666b2dbcd50
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for mcp-service-registry 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page