protolabs42/MCPCore

MCPCore (Python)

MCPCore is a modular, production-ready MCP server scaffold with auto-discovered Prompts, Tools, Resources; Streamable HTTP; API keys/Bearer auth with scopes & revocation; rate limiting; Admin CLI; Docker/Compose; Helm chart; and CI.

Repository: https://github.com/protolabs42/MCPCore

Quick start (Streamable HTTP)

uv add "mcp[cli]" pydantic starlette uvicorn redis typer
uv run mcp-core   # serves streamable HTTP at http://127.0.0.1:8000/mcp
# STDIO fallback
uv run mcp-core-stdio   # or: ANY_MCP_ENABLE_HTTP=false uv run mcp-core

Before exposing the server, set explicit security env vars:

export ANY_MCP_ENABLE_AUTH=true
export ANY_MCP_KEYS_PATH=./keys.json
export ANY_MCP_CORS_ALLOW_ORIGINS=http://localhost:5173

Add to a client (e.g., Claude Desktop) via .mcp.json:

{
  "mcpServers": { "mcpcore": { "command": "uv", "args": ["run", "mcp-core"] } }
}

Streamable HTTP + Auth + Rate Limits

export ANY_MCP_HTTP_HOST=0.0.0.0
export ANY_MCP_HTTP_PORT=8000
export ANY_MCP_HTTP_PATH=/mcp
export ANY_MCP_CORS_ALLOW_ORIGINS=http://localhost:5173,http://localhost:3000
export ANY_MCP_CORS_EXPOSE_HEADERS=Mcp-Session-Id

# Keys in JSON &/or Redis
export ANY_MCP_ENABLE_AUTH=true
export ANY_MCP_KEYS_PATH=./keys.json
export ANY_MCP_REDIS_URL=redis://localhost:6379/0

# Rate limiting
export ANY_MCP_RATE_LIMIT=true
export ANY_MCP_RATE_WINDOW_S=60
export ANY_MCP_RATE_MAX=300

uv run mcp-core-http

Client examples

• curl health check:

  curl -H "Authorization: Bearer sk_live_demo" http://127.0.0.1:8000/healthz
  

• Python fastmcp client:

  import asyncio
  from fastmcp import Client
  
  async def main():
      async with Client("http://127.0.0.1:8000/mcp") as client:
          tools = await client.list_tools()
          print("Tools:", [t.name for t in tools])
          result = await client.call_tool("ping", {})
          print("Ping:", result.data)
  
  asyncio.run(main())
  

Admin CLI

# add a key with scopes
uv run mcp-core-admin keys add --key sk_live_ABC --scopes tools:*,resources:*,prompts:*
# list/revoke/update
uv run mcp-core-admin keys list
uv run mcp-core-admin keys revoke --key sk_live_ABC
uv run mcp-core-admin keys set-scopes --key sk_live_ABC --scopes tools:ping,resources:time
# clean up revoked entries (JSON or Redis stores)
uv run mcp-core-admin keys cleanup

Reverse proxy

Make sure your proxy preserves Authorization, X-API-Key, and Mcp-Session-Id headers; expose Mcp-Session-Id via CORS.

Kubernetes

Use the Helm chart in chart/. Set image, env, and ingress in values.yaml:

helm upgrade --install mcpcore ./chart

Add your own features

Drop files and they'll auto-register:

• src/mcp_core/tools/my_tool.py with @mcp.tool()
• src/mcp_core/resources/my_res.py with @mcp.resource("scheme://{param}")
• src/mcp_core/prompts/my_prompt.py with @mcp.prompt()

Best practices

See BEST_PRACTICES.md for guidance on tool/resource design, security, performance, testing, and operations tailored to this repo.

Security tips

• Defaults are permissive for local dev: before production, enable auth, pin ANY_MCP_CORS_ALLOW_ORIGINS, and run behind TLS.
• Prefer Redis-backed rate limiting and store keys in a vault or secrets manager.
• Rotate keys regularly, revoke unused ones, and run uv run mcp-core-admin keys cleanup to purge stale entries.

Development workflow

• Install dev deps: uv pip install -e .
• Run checks: ./scripts/check.sh
• Tools auto-register from src/mcp_core/{tools,resources,prompts}; add accompanying tests under tests/.