MCP Instructions Server

Shared Claude instructions for teams. Edit instructions.yaml, everyone gets updates.

Quick Start

Option 1: Docker (Recommended)

docker compose up -d
# Server runs at http://localhost:8080/mcp

Option 2: Python

# macOS / Linux
./setup.sh
python server.py

# Windows
python -m venv .venv && .venv\Scripts\activate && pip install -r requirements.txt
python server.py

Option 3: Cloud (Railway)

Deploy on Railway

Set environment variables:

MCP_TRANSPORT=streamable-http
PORT=8080

Option 4: Azure Container Instances

./deploy.sh

Requirements: Azure CLI (az) and Docker installed.

The script creates:

Resource Group
Azure Container Registry
Container Instance with public URL

Redeploy after changes:

# Set your ACR name (check Azure portal or use: az acr list -g rg-mcp-server --query "[0].name" -o tsv)
ACR=your-acr-name

# Build, push and restart
az acr login -n $ACR
docker build -t $ACR.azurecr.io/mcp-server:latest .
docker push $ACR.azurecr.io/mcp-server:latest
az container restart -g rg-mcp-server -n mcp-server

Useful commands:

az container logs -g rg-mcp-server -n mcp-server      # View logs
az container restart -g rg-mcp-server -n mcp-server   # Restart
az group delete -n rg-mcp-server --yes                # Delete all

Which Option to Choose?

Mode	Best For	Cost	Latency
stdio (local Python)	Personal use	Free	~0ms
Docker	Local dev/testing	Free	~10ms
Railway	Quick deploy	Pay per use	~100ms+
Azure ACI	Team sharing, Azure users	~$1-2/month	~100ms+

Note: The server only gets called when you invoke a prompt (/team-instructions:production, etc.). Normal Claude messages don't hit the server. Instructions are loaded once into the conversation context.

Connect Claude Code

Create config file:

Global (all projects): ~/.claude/mcp.json
Per-repo (this project only): .mcp.json in repo root

Remote server (Docker/Railway/Cloud)

{
  "mcpServers": {
    "team-instructions": {
      "type": "streamable-http",
      "url": "https://your-server-url/mcp"
    }
  }
}

Local Python (STDIO)

macOS / Linux:

{
  "mcpServers": {
    "team-instructions": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "team-instructions": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\server.py"]
    }
  }
}

Environment Variables

Variable	Default	Description
`MCP_TRANSPORT`	`stdio`	Transport: `stdio`, `streamable-http`, or `sse`
`PORT`	`8080`	Server port (for HTTP transports)
`MCP_PORT`	`8080`	Alternative port variable

Available Commands

Prompts

Prompt	Description
`production`	Strict mode with team standards
`freestyle`	No rules, full freedom
`code_review`	Review code with standards

Tools

Tool	Description
`help`	List all commands
`refresh`	Reload instructions from file

Resources

Resource	Description
`instructions://core`	Core principles
`instructions://production`	Production guidelines
`instructions://checklist`	Delivery checklist
`instructions://all`	All sections combined

Edit Instructions

Edit instructions.yaml
Call refresh tool (or restart server)
Done - all connected clients get updates

Transports

Transport	Use Case	Endpoint
`streamable-http`	Remote/Cloud (recommended)	`/mcp`
`sse`	Remote/Cloud (legacy)	`/sse`
`stdio`	Local Python execution	N/A

Troubleshooting

Issue	Fix
Server not found	Use absolute paths, check JSON syntax
Python errors	Need Python 3.10+, run `pip install -r requirements.txt`
Connection refused	Check `MCP_TRANSPORT` and port settings
Invalid Host header	Server needs `MCP_TRANSPORT=streamable-http` or `sse`

Test Server

# Health check (SSE transport only - not available in streamable-http)
curl http://localhost:8080/health

# Test streamable-http endpoint
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Note: The /health endpoint only exists when using SSE transport. For streamable-http, use the MCP endpoint test above.