<!-- mcp-name: com.smplkit/mcp -->

smplkit MCP Server

A hosted, agent-native Model Context Protocol server — the gateway that lets an AI agent (Claude Code, Claude Desktop, Cursor, …) operate the smplkit platform on your behalf, without you ever leaving the chat.

Available now: Smpl Jobs — create, run, and monitor scheduled HTTP jobs. More of the smplkit platform will be exposed here over time.

Once connected, tell your agent "POST my endpoint every morning at 7." It creates the recurring job, runs it once on the spot to prove it works (a real 200 with the captured response body), and later answers "has anything failed?" straight from run history.

It is a thin, stateless HTTP client to the smplkit Jobs API. Your smplkit API key is forwarded per request and never stored.

Connect once

1. Get a smplkit API key

Sign up at https://smplkit.com. Use Google or Microsoft (SSO) — an SSO sign-up is email-verified instantly, so you can mint a key right away. Then create an API key in the console.

2. Add the server to your MCP client

The server lives at https://mcp.smplkit.com/api/mcp. Authenticate with your key via the Authorization: Bearer <key> header (a custom X-Smplkit-Api-Key header is also accepted).

Claude Code (CLI):

claude mcp add --transport http smplkit https://mcp.smplkit.com/api/mcp \
  --header "Authorization: Bearer YOUR_SMPLKIT_API_KEY"

…or in .mcp.json:

{
  "mcpServers": {
    "smplkit": {
      "type": "http",
      "url": "https://mcp.smplkit.com/api/mcp",
      "headers": { "Authorization": "Bearer ${SMPLKIT_API_KEY}" }
    }
  }
}

Cursor (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "smplkit": {
      "url": "https://mcp.smplkit.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:SMPLKIT_API_KEY}" }
    }
  }
}

Claude Desktop (claude_desktop_config.json) — Desktop bridges remote servers through mcp-remote. Note the header value has no space after the colon in args (a known mcp-remote quirk); the spaced value goes in env:

{
  "mcpServers": {
    "smplkit": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mcp.smplkit.com/api/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer YOUR_SMPLKIT_API_KEY" }
    }
  }
}

3. Ask your agent

"Create a job that POSTs to https://api.example.com/cache/warm every morning at 7am New York time, then run it now to prove it works."

The agent calls create_job (recurring) then run_job, and shows you the real 200 and captured body. Follow up with:

"List my jobs." · "Has anything failed in the last day?" · "Move the cache warm to 8am." · "Run the digest job now and show me what it returned."

Tools

Tool	What it does
list_jobs	List jobs, each with its latest run status
get_job	One job's configuration
create_job	Create a job (kind inferred from the schedule)
update_job	Change a job (partial change, full-replace under the hood)
delete_job	Remove a job (run history is retained)
run_job	Fire one run now and return the captured response
list_runs	Runs by job / status / time window (the "did it fail?" path)
get_run	One run: status, timing, and the captured HTTP response

create_job infers the kind: a cron schedule → recurring, a run_at datetime → one-off, neither → manual. You never set a kind.

The public-URL constraint

smplkit calls your target URL from the cloud, so it must be reachable from the public internet — localhost/private addresses won't fire. To schedule against a local server, point at its deployed URL or expose it with a tunnel (cloudflared tunnel --url http://localhost:PORT or ngrok http PORT) and set a secret auth header on the job. The bundled SKILL.md teaches an agent this flow.

Development

python3.13 -m venv .venv && . .venv/bin/activate
pip install -r requirements-test.txt
pytest                                          # unit tests (acceptance deselected)
ruff check src tests

Run the server locally:

PYTHONPATH=src uvicorn smplkit_mcp.app:app --host 0.0.0.0 --port 8000
# MCP endpoint:  http://localhost:8000/api/mcp
# Health check:  http://localhost:8000/health

Configuration (env vars):

• JOBS_BASE_DOMAIN — Jobs API host (default jobs.smplkit.com).
• JOBS_SCHEME — https (default) or http.
• JOBS_BASE_URL — full base-URL override (e.g. http://localhost:8005); wins over the two above. Used for the local platform and tests.

Acceptance tests

tests/test_acceptance.py provisions an ephemeral verified account, drives all eight tools against a real Jobs service end-to-end, and cleans up. These tests require smplkit-internal admin credentials, so they self-skip unless an admin key is available (ADMIN_API_KEY env or the [admin] profile in ~/.smplkit) — external contributors can ignore them; the unit suite needs no credentials. Run them explicitly:

pytest -m acceptance
# point at a non-prod Jobs service with JOBS_BASE_URL=...

Architecture

• Stateless Python service built on FastMCP: it holds no database and no platform credential of its own.
• Auth is per request — your API key arrives as a header, is forwarded as the Bearer token to the smplkit API, and is never cached or logged.
• The MCP endpoint is served under /api/mcp with a stateless, JSON-response transport (no long-lived SSE), so it behaves correctly through proxies and load balancers with short idle timeouts.

License

MIT.