Skip to main content

​
Transport Modes

automagik-tools supports three transport modes for MCP communication.

​
stdio

​
Protocol

JSON-RPC 2.0 over standard input/output pipes.

​
Connection Model

1:1 process relationship. AI agent spawns automagik-tools as subprocess.

​
Latency

~1ms (inter-process communication)

​
Usage

# Claude Desktop spawns process
spawn("uvx", ["automagik-tools", "serve"])

# Communication via pipes
Agent stdin → Tools stdout
Tools stdin ← Agent stdout

​
Configuration

Claude Desktop: 
{
  "mcpServers": {
    "automagik-tools": {
      "command": "uvx",
      "args": ["automagik-tools", "serve"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}
Cursor: 
{
  "mcp": {
    "servers": {
      "automagik-tools": {
        "command": "uvx automagik-tools serve"
      }
    }
  }
}

​
Characteristics

  • No network ports opened
  • Process-isolated execution
  • Automatic lifecycle management
  • Single-user only
  • No remote access

​
SSE (Server-Sent Events)

​
Protocol

JSON-RPC 2.0 over HTTP long-polling with server-push.

​
Connection Model

Many:1 server. Multiple agents connect to persistent server.

​
Latency

~50ms (HTTP overhead + network)

​
Usage

Start server: 
automagik-tools serve --transport sse --port 3000

# Server listening at http://localhost:3000
# SSE endpoint: /sse
# Health check: /health
Client connection: 
GET /sse HTTP/1.1
Host: localhost:3000
Accept: text/event-stream
Authorization: Bearer YOUR_TOKEN

# Server establishes SSE stream
HTTP/1.1 200 OK
Content-Type: text/event-stream
Connection: keep-alive

# Server pushes events
event: tools-update
data: {"tools": [...]}

event: tool-result
data: {"result": {...}}

​
Configuration

# Basic
automagik-tools serve --transport sse

# With auth
automagik-tools serve \
  --transport sse \
  --port 3000 \
  --auth-token SECRET

# With HTTPS
automagik-tools serve \
  --transport sse \
  --port 3000 \
  --ssl-cert cert.pem \
  --ssl-key key.pem
Docker: 
FROM python:3.11-slim
RUN pip install automagik-tools
EXPOSE 3000
CMD ["automagik-tools", "serve", \
     "--transport", "sse", \
     "--port", "3000", \
     "--host", "0.0.0.0"]

​
Characteristics

  • Persistent HTTP connections
  • Real-time event push
  • Multiple concurrent clients
  • Stateful session management
  • Requires network access

​
HTTP

​
Protocol

JSON-RPC 2.0 over HTTP request-response.

​
Connection Model

Stateless REST API. Each request independent.

​
Latency

~100ms (HTTP overhead + network + connection setup)

​
Usage

Start server: 
automagik-tools serve --transport http --port 8080

# REST API at http://localhost:8080
# OpenAPI docs: /docs
# Health check: /health
API endpoints: List tools: 
curl http://localhost:8080/tools

# Response
{
  "tools": [
    {
      "name": "genie_execute",
      "description": "...",
      "parameters": {...}
    }
  ]
}
Call tool: 
curl -X POST http://localhost:8080/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "tool": "genie_execute",
    "arguments": {...}
  }'

# Response
{
  "success": true,
  "result": {...}
}
Batch call: 
curl -X POST http://localhost:8080/tools/batch \
  -H "Content-Type: application/json" \
  -d '{
    "calls": [
      {"tool": "tool1", "arguments": {...}},
      {"tool": "tool2", "arguments": {...}}
    ]
  }'

# Response
{
  "results": [
    {"success": true, "result": {...}},
    {"success": true, "result": {...}}
  ]
}

​
Authentication

API key: 
automagik-tools serve \
  --transport http \
  --auth-type apikey \
  --api-keys key1,key2

curl -H "X-API-Key: key1" http://localhost:8080/tools
Bearer token: 
automagik-tools serve \
  --transport http \
  --auth-type bearer \
  --auth-token SECRET

curl -H "Authorization: Bearer SECRET" http://localhost:8080/tools

​
Characteristics

  • Stateless requests
  • Standard REST API
  • Horizontal scaling support
  • OpenAPI documentation
  • Load balancing compatible

​
Technical Comparison

FeaturestdioSSEHTTP
ProtocolJSON-RPC/stdinJSON-RPC/SSEJSON-RPC/REST
Connection1:1 processMany:1 persistentStateless
Latency1ms50ms100ms
NetworkNoYesYes
Real-time pushNoYesNo
Scalability1 user10-100 usersUnlimited
StatePer processPersistentNone
AuthProcess isolationBearer/API keyBearer/API key

​
Performance Measurements

Measured on local machine (Linux, 6 cores):
OperationstdioSSEHTTP
Tool discovery0.8ms48ms95ms
Simple tool call1.2ms52ms103ms
Tool with I/O15ms63ms112ms
Batch 10 tools12ms180ms420ms

​
Use Cases

​
stdio

  • Single developer local setup
  • AI clients: Claude Desktop, Cursor, Windsurf
  • Maximum security (no network)
  • Development and testing

​
SSE

  • Team sharing (5-50 users)
  • Remote development
  • Cloud deployment
  • Real-time notifications
  • CI/CD integration

​
HTTP

  • Programmatic API access
  • Service integrations
  • Webhooks
  • Frontend applications
  • Large scale deployment (50+ users)
  • Kubernetes/cloud native

​
Security

​
stdio

  • No network exposure
  • Process-level isolation
  • Credentials via environment variables
  • No authentication needed (local-only)

​
SSE

  • HTTPS required for production
  • Bearer token authentication
  • CORS controls
  • Rate limiting per client
  • Connection monitoring

​
HTTP

  • HTTPS required for production
  • API key or OAuth authentication
  • CORS controls
  • Rate limiting per endpoint
  • Request logging

​
Mixed Mode

Run multiple transports simultaneously: 
automagik-tools serve \
  --transport stdio,sse,http \
  --sse-port 3000 \
  --http-port 8080

# Available via:
# - stdio for local agents
# - SSE at http://localhost:3000
# - HTTP at http://localhost:8080

​
Environment Variables

# Transport configuration
TOOLS_TRANSPORT=sse
TOOLS_PORT=3000
TOOLS_HOST=0.0.0.0

# Authentication
TOOLS_AUTH_TOKEN=your_secret
TOOLS_API_KEYS=key1,key2

# SSL
TOOLS_SSL_CERT=/path/to/cert.pem
TOOLS_SSL_KEY=/path/to/key.pem

# CORS
TOOLS_ALLOWED_ORIGINS=https://app.example.com

# Limits
TOOLS_MAX_CONNECTIONS=100
TOOLS_RATE_LIMIT=1000

# Start with config
uvx automagik-tools serve --env .env

​
Next Steps