# BuildMyMCPServer — full documentation

> Turn a natural-language prompt into a hosted, OAuth 2.1-protected Model Context Protocol (MCP) server in about 60 seconds. This file condenses the full documentation at https://buildmymcpserver.com/docs for LLM consumption. See https://buildmymcpserver.com/llms.txt for the short index.

## Quickstart (https://buildmymcpserver.com/docs)

Describe the tool you want, paste in any credentials, watch the build stream, copy a snippet into your AI client. Five minutes from first prompt to a live OAuth-protected MCP server.

Prerequisites: an MCP-capable AI client (Claude Desktop, Cursor, ChatGPT Custom Connectors, VS Code Copilot, Continue.dev) and API credentials for whatever the server should access — or pick the echo example to skip credentials.

1. **Sign in** to the dashboard.
2. **Describe your tool** in plain language. Example prompt: "Search and read pages from our Notion workspace via the Notion API. Tools: search_pages(query), get_page_content(page_id). Auth: NOTION_API_KEY."
3. **Confirm the plan.** The wizard shows which tools were parsed from the prompt, the input schemas, and which credentials are needed. Everything is editable before the build starts.
4. **Watch the build stream** over WebSocket through five states: queued → generating (Claude returns the spec) → building (TypeScript rendered, static checks, Docker image) → deploying (container boot) → live (endpoint responds, OAuth gate active).
5. **Install in your client.** The Done screen shows copy-ready snippets for Claude Desktop, Cursor and ChatGPT. The OAuth handshake runs automatically on the first tool call.

Example client config:

    {
      "mcpServers": {
        "notion-reader": {
          "url": "https://<your-server>.mcp.buildmymcpserver.com/mcp",
          "auth": "oauth2"
        }
      }
    }

## MCP concepts (https://buildmymcpserver.com/docs/concepts)

Model Context Protocol is an open standard from Anthropic for connecting AI assistants to external tools, data and APIs. Three primitives, one transport:

- **Tools** — functions the AI can invoke. Each has a name, description, input schema (JSON Schema/Zod) and a server-side implementation. The AI decides when to call them based on the description.
- **Resources** — read-only, URI-addressed data the AI can fetch (files, documents, database records).
- **Prompts** — parameterized prompt templates the server exposes to encourage specific orchestration patterns.

**Transport: Streamable HTTP.** Every generated server speaks Streamable HTTP (MCP spec 2025-11-25). The older SSE transport was deprecated in June 2025 and is not supported. One HTTP endpoint at /mcp, optionally negotiating a long-lived text/event-stream when the server pushes updates.

**Session lifecycle:** initialize (client sends protocol version + capabilities; server assigns a session id via the mcp-session-id header) → notifications/initialized → tools/list, tools/call, resources/list, prompts/list.

**Why MCP and not just REST:** REST APIs need bespoke OpenAPI integration per client. MCP standardizes discovery, invocation, auth and streaming, so any spec-compliant client picks up any spec-compliant server with zero glue code.

## OAuth 2.1 flow (https://buildmymcpserver.com/docs/oauth)

Every generated server is an OAuth 2.1 Resource Server; the control plane is the Authorization Server. Standards implemented:

- OAuth 2.1 draft (draft-ietf-oauth-v2-1) — no implicit flow, mandatory PKCE
- RFC 8414 — Authorization Server Metadata
- RFC 9728 — Protected Resource Metadata
- RFC 8707 — Resource Indicators (audience binding)
- RFC 7591 — Dynamic Client Registration

End-to-end: the first unauthenticated request gets a 401 with a WWW-Authenticate header pointing at the server's protected-resource metadata. The client fetches it, discovers the authorization server, registers itself dynamically (no human in the loop; each AI surface gets its own ephemeral client identity), then runs Authorization Code + PKCE. The user consents, the client exchanges the code for an RS256-signed JWT bound to the specific server's resource URL. The runner verifies signature (against the AS JWKS), issuer, audience and expiry on every call. No token passthrough — the runner never forwards the client's token to a downstream API.

Why audience binding matters: without RFC 8707, a token issued for one customer's MCP server could be replayed against another customer's server.

## Authoring tools (https://buildmymcpserver.com/docs/authoring)

What you write in the prompt is what Claude turns into TypeScript. Rules the generator enforces on generated code:

- No eval, no new Function, no child_process — static checks reject the build.
- No import statements in tool bodies; the runtime injects fetch, pg and z (Zod).
- Secrets live in process.env, never embedded literally.
- External HTTP calls must use AbortSignal.timeout (default 10s).
- Database access via pg with parameterized queries only.
- Errors return as MCP error-content, not thrown exceptions.

Prompt patterns that work: be explicit about tool names ("Tool: search_pages(query)"); name the credentials ("Auth: NOTION_API_KEY"); flag destructive tools so clients can warn; one server per integration rather than one server per tool.

Iteration: open the server's Iterate tab, describe the change, a new build version is queued and rolling-deployed — the old version stays live until the new one is healthy.

## Self-hosting (https://buildmymcpserver.com/docs/self-hosting)

The control plane and generator are open. Requirements: Node.js 20+, pnpm 9+, a Docker engine reachable from the generator, Postgres 16+, Redis 7+, and an Anthropic API key (optional — a mock generator covers offline dev).

Key environment variables: DATABASE_URL, REDIS_URL, ANTHROPIC_API_KEY, SECRETS_ENCRYPTION_KEY (32-byte hex AES-256-GCM key), CONTROL_PLANE_PUBLIC_URL (OAuth issuer), OAUTH_KEY_DIR (RS256 keypair), RUNNER_PORT_RANGE_START/END (host-port window for generated containers).

Production container sandboxing flags: --read-only, --cap-drop=ALL, --security-opt=no-new-privileges, --cpus=0.5 --memory=512m.

## FAQ highlights (https://buildmymcpserver.com/docs/faq)

- **How does LLM-generated code stay safe?** Three layers: strict Zod validation of the JSON spec, a regex scan for banned tokens (eval, child_process, prompt-injection markers), and a static check on the rendered TypeScript before the Docker build. Any failure stops the deploy.
- **What if Claude generates a broken tool?** The build fails at static-check or Docker-build stage; the user sees the exact error in the live log, refines the prompt and rebuilds. No invalid server serves traffic.
- **Do secrets leave the environment?** No. AES-256-GCM encrypted at rest, decrypted only when injected into the container at boot. Never in audit logs, build logs, or prompts sent to Claude.
- **No API key?** The generator falls back to a deterministic mock spec (echo + now tools) so the full pipeline can be verified without credits.

## Pricing (https://buildmymcpserver.com/pricing)

- Hobby: €0 — 1 server, 100,000 tool calls/month, community support.
- Pro: €49/month — 5 servers, 1M tool calls/month, priority build queue, email support. Custom domains on the roadmap.
- Team: €199/month — 25 servers, 10M tool calls/month, audit log, Slack support. RBAC on the roadmap.
- Enterprise: custom — unlimited servers; infrastructure, data residency, SSO/SAML scoped per contract.
