MCP Platform

A reusable Model Context Protocol (MCP) Platform for hosting MCP servers, tool registries, and skills-powered AI workflows over HTTP.

What This Repo Is

This is the platform repo — shared runtime infrastructure that any project-specific MCP service builds on top of.

Repo type	Purpose	Example
Platform (this repo)	HTTP server, tool registry, validation, auth, logging	`MCP`
Skills content	Reusable AI agent skill definitions (SKILL.md + references)	`AI_AGENT_SKILLS`
Project service	Business-logic tools for a specific product	`ghostfolio-mcp-server`

A project service imports this platform, registers its own tools, and pins a version of the skills content repo for context retrieval.

Architecture

AI_AGENT_SKILLS (content)
        ↓ mounted / submodule
  Project MCP Service (e.g. ghostfolio-mcp-server)
        ↓ depends on
    MCP Platform (this repo) ← HTTP transport, registry, validation
        ↓ serves
    Claude / AI client via JSON-RPC over HTTP

Quickstart

# 1. Install dependencies
npm install

# 2. Set environment variables (optional)
export PORT=3100
export MCP_API_KEY=your-secret-key   # omit to disable auth

# 3. Run the dev server
npm run dev

# 4. Health check
curl http://localhost:3100/health
# → { "status": "ok", "timestamp": "..." }

# 5. List registered tools
curl http://localhost:3100/tools
# → { "tools": [ { "name": "echo", ... } ] }

# 6. Call a tool via JSON-RPC
curl -X POST http://localhost:3100/rpc \
  -H "Content-Type: application/json" \
  -H "x-mcp-api-key: your-secret-key" \
  -d '{"method":"echo","params":{"message":"hello"},"id":1}'
# → { "jsonrpc": "2.0", "result": { "echo": "hello", ... }, "id": 1 }

Adding a Tool

Create a handler function: (params, context) => result
Define a JSON schema for the input parameters.
Register it in src/server/toolRegistry.ts or via registerTool().
See docs/adding_a_tool.md for the full guide.

Deployment

Designed for Railway with HTTP transport (no stdio).

Set PORT via Railway env vars (Railway auto-assigns).
Set MCP_API_KEY for production auth.
See docs/deployment_railway.md for step-by-step instructions.

Project Structure

src/
  index.ts              # Entrypoint — bootstraps server
  server/               # HTTP server, transport, tool registry
  skills/               # Skills file loader and resolver
  validation/           # JSON schema + SQL safety gate
  auth/                 # API key auth + request context
  logging/              # Structured logger + trace
  utils/                # Error classes, env helpers
docs/                   # Architecture, deployment, guides
templates/              # Tool, skill, and service repo templates
examples/               # Minimal working tool example

License

MIT