speculate-mcp

MCP server for any OpenAPI-described API. Gives AI agents the ability to resolve, explore, and execute calls against any REST API with an OpenAPI spec — without writing custom integration code.

What it does

Five tools, covering the full integration loop:

Install

The recommended way — no global install needed:

uvx speculate-mcp

Or install globally:

pip install speculate-mcp
# or
uv tool install speculate-mcp

Configure your AI IDE

Claude Code (~/.claude.json or project .claude/settings.json)

{
  "mcpServers": {
    "speculate": {
      "command": "speculate-mcp",
      "env": {
        "SPECULATE_API_KEY": "your-key-here"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "speculate": {
      "command": "speculate-mcp",
      "env": {
        "SPECULATE_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "speculate": {
      "command": "speculate-mcp",
      "env": {
        "SPECULATE_API_KEY": "your-key-here"
      }
    }
  }
}

Get your API key at speculateapi.dev. Free tier works without a key (rate-limited).

Usage example

Once connected, your agent can do things like:

Load the Stripe API, find the endpoint to create a payment intent,
and make a test call with amount=1000, currency=usd.

The agent will call resolve_spec("stripe"), then search_endpoints(...), then execute_call(...) — all automatically.

Environment variables

Self-hosting

Run the backend yourself:

cd backend
cp .env.example .env
# Set OPENAI_API_KEY in .env
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

Then point the MCP server at your instance:

SPECULATE_API_URL=http://localhost:8000 speculate-mcp

Publishing to PyPI

Releases are automated via GitHub Actions. To publish a new version:

1. Update version in pyproject.toml
2. Tag and push:

   git tag mcp-v0.3.0
   git push --tags
   

The publish-mcp.yml workflow builds and publishes via PyPI trusted publishing (no stored secret needed — requires a configured PyPI environment named pypi).

License

MIT