kyb-mcp

A KYB (Know Your Business) workbench exposed over the Model Context Protocol. It searches the French company registry (SIRENE / RNE through the free recherche-entreprises.api.gouv.fr API), keeps review dossiers in PostgreSQL, and exposes all of it to Claude Code, claude.ai or any MCP client.

Built on the MCP Python SDK v2 (protocol revision 2026-07-28) as a learning project that uses every protocol primitive on purpose: tools, resources, prompts, completions, elicitation, sampling, progress, change notifications, stdio and Streamable HTTP.

┌────────────┐  stdio / Streamable HTTP  ┌──────────────────────────┐   https   ┌────────────────────────┐
│ MCP client │ ◄───────────────────────► │ kyb-mcp (MCPServer)      │ ────────► │ recherche-entreprises  │
│ Claude Code│   tools · resources ·     │  tools/  resources.py    │ 5 req/s   │ .api.gouv.fr (public)  │
│ claude.ai  │   prompts · completions   │  prompts.py  core.py     │           └────────────────────────┘
│ Inspector  │   elicit · sample ·       │  db/repo.py (port)       │   SQL     ┌────────────────────────┐
└────────────┘   progress · notify       │   ├ InMemoryDossierRepo  │ ────────► │ PostgreSQL             │
                                         │   └ PostgresDossierRepo  │           │ (Compose local / Neon) │
                                         └──────────────────────────┘           └────────────────────────┘

Quick start

uv sync
uv run kyb-mcp                     # stdio server, in-memory dossiers, no config needed
uv run mcp dev src/kyb_mcp/server.py   # same server inside the MCP Inspector (needs Node)

Register it in Claude Code (stdio):

claude mcp add kyb -- uv run --directory /absolute/path/to/kyb-mcp kyb-mcp

Then try: "Find the company Qonto, open a dossier for it and run the KYB review prompt."

What the server exposes

All tool calls to the registry go through one httpx.AsyncClient with a token bucket (5 req/s, the public limit is 7) and a 60 s cache. Directors' birth dates are dropped before anything leaves the process.

Configuration

Streamable HTTP, Docker, Compose

uv run uvicorn kyb_mcp.http:app --port 8000          # http://127.0.0.1:8000/mcp  (+ /healthz)
claude mcp add --transport http kyb-http http://127.0.0.1:8000/mcp

docker compose up -d --build                         # PostgreSQL 16 (host port 5433) + server on :8000

Tagged releases publish ghcr.io/igitscor/kyb-mcp with an SBOM and provenance attestation (.github/workflows/image.yml).

Deploy (Vercel Hobby + Neon, no credit card)

1. npm i -g vercel@latest && vercel login with your personal account, then vercel link.

2. Create a free Neon project and add its DSN: vercel env add DATABASE_URL production.

3. vercel env add KYB_REQUEST_STATE_KEY production with python -c "import secrets; print(secrets.token_hex(32))".

4. vercel deploy --prod. The entrypoint is kyb_mcp.http:app (see [tool.vercel] in pyproject.toml).

5. Point Claude Code at https://<project>.vercel.app/mcp, or add it as a claude.ai custom connector.

Why this host and database: ADR 0004.

Development

uv run pytest                                        # 23 offline tests (respx mocks the registry)
docker compose up -d db && KYB_TEST_DATABASE_URL=postgresql://kyb:kyb@localhost:5433/kyb uv run pytest tests/test_repo_postgres.py
uv run ruff check && uv run ruff format --check && uv run pyright

CI runs the same on every push with a PostgreSQL service container, then builds the Docker image and smoke-tests /healthz and server/discover.

Design notes

• ADR 0001: why SDK v2 / protocol 2026-07-28, and what changed from FastMCP.

• ADR 0002: PostgreSQL behind a repository port, in-memory adapter for zero-setup runs.

• ADR 0003: stateless HTTP, DNS-rebinding protection, shared request-state key.

• ADR 0004: hosting comparison and the no-card constraint.

• SECURITY.md: data handling, transport exposure, what is not protected yet.

Learning path (how this repo was built)

Next steps

• OAuth 2.1 resource server (AuthSettings + TokenVerifier) before exposing write tools publicly.

• OpenTelemetry exporter: the SDK already emits a span per request; add opentelemetry-sdk and an OTLP endpoint.

• Publish to the official MCP Registry with mcp-publisher.

License

MIT. Registry data is public data from INSEE / INPI under the Licence Ouverte 2.0.