DEV Community

Stefan
Stefan

Posted on

How to Build an Internal MCP Registry

If you connect an AI coding assistant to local tools today, you probably rely on the Model Context Protocol (MCP). By default, MCP clients connect directly to tools declared in local settings files API Evangelist on MCP. A developer adds a command to their editor config, and the agent starts invoking that tool.

That quick setup creates an immediate trust boundary problem. When a developer registers a tool using the stdio transport, the MCP client spawns a local subprocess inheriting the user's OS permissions, environment variables, and network access Yobitel MCP Architecture.

If someone pulls an unvetted package from a public registry, any dependency compromise allows code execution inside the developer's shell Glama on MCP Security. Long-lived corporate credentials frequently end up hardcoded into workstation configuration files TrueFoundry on MCP credentials. Without central governance, teams quickly accumulate shadow integrations and unmonitored access to internal databases.

An internal MCP registry solves this by acting as a single, curated source of truth for approved tools. Here is how the registry works, how to build a working prototype in a local lab, and how to harden it for production.

What an MCP Registry Actually Does

An MCP registry is a metadata directory. It standardises server discovery using a REST API (frozen under the official v0.1 specification) and a uniform schema manifest named server.json MCP Registry v0.1. When an editor starts up, it asks the registry which tools exist, what they do, and where they run.

Crucially, a registry does not proxy runtime traffic or inspect tool arguments Maxim AI on MCP Gateways. The registry acts strictly as the control plane for discovery. The data plane, where the model actually executes requests, is handled separately by an MCP server or gateway.

If you want to review how agent tools should protect sensitive data and parameters during execution, check out the MCP Security Code Review Guide.

Step 1: Write the Manifest (server.json)

Every vetted tool in an MCP registry declares a manifest adhering to the upstream schema MCP Server Schema. This JSON file tells clients how to identify the tool and where its service lives:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "corp.internal/analytics-tool",
  "title": "Internal Analytics Warehouse Tool",
  "description": "Read-only access to sanitized business analytics.",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://mcp-gateway.corp.internal/v1/analytics"
    }
  ],
  "_meta": {
    "corp.internal/governance": {
      "team": "data-platform",
      "approved": true
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Notice that we omitted io.modelcontextprotocol.registry/official from the manifest's _meta section. Under the upstream specification, registry status keys are read-only metadata attached dynamically by the registry server response envelope, not authored by publishers MCP Registry Schema.

Notice also that the remotes block uses streamable-http instead of local stdio. This distinction matters. It keeps execution off developer laptops and routes requests to an isolated internal endpoint.

Step 2: Build a Lab Registry in Python

To see how an editor talks to a registry, you can write a minimal mock service using FastAPI. The official v0.1 specification relies on two primary read endpoints: /v0.1/servers to list tools, and /v0.1/servers/{server_name}/versions/{version} to fetch an exact release.

Standard MCP client discovery queries the latest keyword to resolve the active manifest Permit.io on MCP Registries. Your version lookup handler must accept latest alongside explicit version numbers:

from fastapi import FastAPI, HTTPException
import uvicorn

app = FastAPI(title="Lab MCP Registry")

CATALOG = {
    "corp.internal/analytics-tool": {
        "server": {
            "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
            "name": "corp.internal/analytics-tool",
            "version": "1.0.0",
            "remotes": [{"type": "streamable-http", "url": "https://mcp-gateway.corp.internal/v1/analytics"}]
        },
        "_meta": {"corp.internal/governance": {"team": "data-platform", "approved": True}}
    }
}

@app.get("/v0.1/servers")
async def list_servers():
    return {"servers": list(CATALOG.values())}

@app.get("/v0.1/servers/{server_name:path}/versions/{version}")
async def get_server(server_name: str, version: str):
    entry = CATALOG.get(server_name)
    if not entry:
        raise HTTPException(status_code=404, detail="Server not found")
    if version != "latest" and entry["server"]["version"] != version:
        raise HTTPException(status_code=404, detail="Version not found")
    return entry

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8080)
Enter fullscreen mode Exit fullscreen mode

You can query this service immediately with curl:

curl -s http://127.0.0.1:8080/v0.1/servers | jq .
Enter fullscreen mode Exit fullscreen mode

The client receives the verified remote endpoint and metadata. It now knows which servers are legitimate without relying on ad-hoc workstation configs.

Moving from Lab to Production

A small Python dictionary works for local testing, but running a registry across an entire engineering organisation requires three structural changes.

1. Run the Upstream Registry Service

In production, avoid maintaining custom registry endpoints. Rather than maintaining custom API routing, run the official containerised Go registry service (ghcr.io/modelcontextprotocol/registry) backed by PostgreSQL within your private cloud network MCP Registry Self-Hosting.

Keep this service inside your corporate perimeter. Placing it on an internal subnet or behind a corporate VPN keeps discovery safe from outside access.

2. Manage Tools Through GitOps

Do not let developers register tools directly against the production database. Instead, store all server.json manifests in an internal Git repository. Require pull requests to pass automated linting and security review Pinterest Engineering.

In your CI pipeline, validate three boundaries before merging any manifest:

  1. Run JSON schema validation against the official schema URL.
  2. Ensure the name begins with your corporate namespace (such as corp.internal/).
  3. Check that remote URLs point only to approved internal gateway hosts.

3. Enforce Workstation Allowlist Controls

An internal registry is ineffective if developers can still install arbitrary tools from the public internet. While GitHub Copilot provides a "Registry only" toggle in public preview, it relies on server name matching GitHub Copilot MCP Controls. For tamper-resistant enforcement on developer laptops, combine that toggle with managed allowlists in managed-settings.json so developers cannot override policy locally.

Finally, make sure the endpoints listed in your registry route through an authenticated gateway. Use an MCP gateway to terminate mutual TLS or OAuth 2.1 tokens, audit tool parameters, and enforce rate limits. If you want to see how attackers abuse excessive tool permissions once an agent connects, read the Agent & Tool Abuse Code Review Guide.

Practical Review Checks

When reviewing an internal MCP registry deployment, check these four areas:

  • Registry separation: Confirm the registry only exposes metadata. Credentials and runtime logic must never appear in server.json.
  • Transport isolation: Reject unvetted local stdio binaries. Point remotes to containerised streamable-http services.
  • Namespace boundaries: Ensure tool names require your internal prefix to prevent naming collisions.
  • Client lock-down: Pair "Registry only" policies with managed-settings.json allowlists so unvetted tools cannot be added manually.

Top comments (0)