MCP Hello CIMD

A Model Context Protocol (MCP) hello world server with a say_hello tool, that also implements the server side of CIMD — Client ID Metadata Documents (https://client.dev/servers).

⚠️ Important: this project is a server, not a client. It serves MCP tools to MCP clients and it consumes CIMD documents exactly as an OAuth authorization server would.

What is CIMD?

CIMD (Client ID Metadata Documents) is a new OAuth approach that lets clients identify themselves using HTTPS URLs instead of preregistration. Instead of a client registry, an authorization server fetches the client's metadata just-in-time from the client_id URL.

This project implements the server-side CIMD processing flow from https://client.dev/servers:

1. Receive OAuth request — client sends client_id as an HTTPS URL
2. Fetch CIMD document — HTTPS GET to the client_id URL with Accept: application/json
3. Validate schema & content — parse JSON, verify required fields, check redirect URIs
4. Enforce policies — SSRF protections, size limits, TTL caching
5. Proceed with OAuth flow — return the validated metadata

Features

MCP (the hello world part)

• say_hello(name) — the classic hello world MCP tool

CIMD (server-side implementation)

• cimd_resolve(client_id) — full CIMD server flow: validate URL → fetch → validate schema → cache
• cimd_cache_info() — admin tool to inspect the metadata cache
• cimd_clear_cache() — admin tool to force re-fetch of metadata

Security (SSRF protections)

• HTTPS only — rejects non-HTTPS client_id URLs immediately
• Private/loopback/link-local address blocking — RFC 1918, 127.0.0.0/8, 169.254.0.0/16, IPv6 equivalents, and more
• DNS rebinding protection — resolves and validates DNS, pins IPs for requests
• TLS validation — validates certificates, modern TLS only
• Size limits — 5 KB max document size (per the CIMD spec)
• Content-Type enforcement — requires application/json
• Redirect limits — max 3 redirects, each hop re-validated
• Cache with TTL — 10 minute default TTL to balance freshness and performance

Installation

pip install -e .

Running the server

The server speaks MCP over stdio:

Or directly:

uvicorn mcp_hello_cimd.main:app --port 8001

Add to an MCP client (e.g. Claude Desktop / Cline)

Add to your MCP settings configuration (mcpServers):

{
  "mcpServers": {
    "hello-cimd": {
      "command": "python",
      "args": ["-m", "mcp_hello_cimd.cli"]
    }
  }
}

The CIMD flow in action

When an OAuth request arrives with a client_id like:

GET /authorize?client_id=https://client.example.com/.well-known/oauth-client-metadata.json&...

cimd_resolve performs the server-side flow:

1. Validate URL format                → must be https://
2. Check cache first                  → TTL 600s, returns if fresh
3. Fetch with SSRF protections        → 5KB limit, 10s timeout, 3 redirects max
4. Parse and validate JSON            → client_id must match URL, redirect_uris required
5. Cache and return metadata          → cached for 10 minutes

Example metadata document a client would host

{
  "client_id": "https://client.example.com/.well-known/oauth-client-metadata.json",
  "client_name": "Example OAuth Client",
  "client_uri": "https://client.example.com",
  "redirect_uris": ["https://client.example.com/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "private_key_jwt",
  "scope": "openid profile email"
}

Error semantics

Per the CIMD server spec, failures produce clear OAuth-style errors:

Condition	Error code
Metadata fetch failed (network, HTTP error)	invalid_client
Malformed JSON / missing required fields	invalid_client_metadata
SSRF violation (non-HTTPS, private IP, etc.)	invalid_client_metadata

Project layout

src/mcp_hello_cimd/
├── __init__.py
├── main.py                # CLI entry point (stdio transport)
├── server.py             # MCP server: say_hello + CIMD tools
└── cimd/
    ├── __init__.py
    ├── ssrf.py           # SSRF protections (blocked ranges, DNS pinning)
    └── processor.py      # CIMD server flow: fetch → validate → cache
tests/
└── test_server.py        # Tests

Testing

pip install -e ".[dev]"
pytest

Resources

• CIMD for Servers
• CIMD IETF Internet-Draft
• Model Context Protocol

running test pytest -k test_say_hello

test client

start server

uvicorn mcp_hello_cimd.main:app --port 8001

And then run the client

python streamable_http_client.py