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.1instead oflocalhostin 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.