speculate-mcp 0.2.0

MCP server for any OpenAPI-described API — resolve, search, and execute

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:

Tool	What it does
resolve_spec	Load any API by name ("Stripe"), doc URL, or direct spec URL
describe_auth	Return exact auth headers, OAuth2 flows, and credential instructions
search_endpoints	Find relevant endpoints with a natural language query
get_endpoint_schema	Return path params, body fields, types, enums, and required flags
execute_call	Execute a live API call and return the response

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

Variable	Default	Description
SPECULATE_API_URL	https://mcp.speculateapi.dev	Backend URL (for self-hosted deployments)
SPECULATE_API_KEY	(empty)	Your Speculate API key
MCP_TRANSPORT	stdio	Set to http to run as an HTTP server instead of stdio
PORT	8080	Port to listen on when MCP_TRANSPORT=http

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