sugra-api-mcp 0.2.0

Connector between LLM agents and world data. 518+ endpoints aggregating 55+ primary sources across financial markets, macroeconomics, company fundamentals, government, physical world, and news. Works with Anthropic Claude, OpenAI GPT, Google Gemini, xAI, and any MCP-enabled IDE.

sugra-api-mcp

Connector between LLM agents and world data. Official Model Context Protocol server for the Sugra API - 518+ endpoints aggregating 55+ primary sources across financial markets, macroeconomics, company fundamentals, government, physical world, and news.

Works with Anthropic Claude, OpenAI GPT, Google Gemini, xAI, and any MCP-enabled IDE.

Client details:

• Anthropic Claude: Claude Desktop, Claude Code (CLI), claude.ai (web)
• OpenAI GPT: ChatGPT (via MCP connector)
• Google Gemini: Gemini CLI, Gemini Code Assist (VS Code + JetBrains)
• xAI: Remote MCP Tools in xAI SDK and Responses API
• IDEs: VS Code (native), Cursor, Zed, Cline, Continue.dev, Windsurf
• Custom agents: anything built on the Python or TypeScript MCP SDK

What you get

17 tools covering the full Sugra API:

Category	Tools
Markets	get_market_price, get_historical_prices, get_market_overview, search_symbol, get_prediction_market
Fundamentals	get_company_overview, get_company_filings
Macro	get_macro_indicator, get_central_bank_rate, search_economic_series
Government	get_government_spending, get_treasury_data
Physical world	get_weather, get_environmental_data
News	get_news
Discovery	search_endpoint, call_endpoint (covers all 518 endpoints)

Installation

pip install sugra-api-mcp

Get a free API key at app.sugra.ai/settings/billing (Free tier: 50 req/day).

Usage with Claude Desktop (stdio)

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sugra": {
      "command": "sugra-api-mcp",
      "env": {
        "SUGRA_API_KEY": "sugra_xxx_yourkey..."
      }
    }
  }
}

Restart Claude Desktop. Sugra tools appear in the tools menu.

Usage with Claude Code (Anthropic CLI)

claude mcp add sugra -- sugra-api-mcp
# then set the env var that sugra-api-mcp reads
export SUGRA_API_KEY=sugra_xxx_...

Or edit ~/.claude/config.json manually with the same shape as Claude Desktop above.

Usage with Cursor, Zed, Cline, Continue.dev, Windsurf

Each of these has an MCP settings file (typically mcp.json or equivalent) with the same stdio config shape as Claude Desktop.

Usage with ChatGPT

ChatGPT supports MCP through its connector UI. Use the hosted HTTP endpoint (below) since ChatGPT does not launch local stdio processes.

Usage over HTTP (claude.ai, ChatGPT, remote agents)

Hosted Streamable HTTP endpoint:

https://app.sugra.ai/mcp

Add to claude.ai, ChatGPT, or any Streamable HTTP MCP client. Authenticate with Authorization: Bearer sugra_xxx_....

In claude.ai: Settings -> Connectors -> Add custom connector. In ChatGPT: Settings -> Connectors -> Add MCP server.

Environment variables

Variable	Required	Default	Description
SUGRA_API_KEY	Yes (stdio)	-	Your Sugra API key. In HTTP mode with OAuth this becomes a fallback for requests without Bearer
SUGRA_API_BASE	No	https://sugra.ai	Override for self-hosted or beta environments
SUGRA_TIMEOUT	No	30	Request timeout in seconds
SUGRA_MCP_ALLOWED_HOSTS	No (HTTP)	-	Comma-separated hostnames to allow behind a reverse proxy

HTTP transport with OAuth (v0.2.0+)

When running with --transport streamable-http the server validates the incoming Authorization: Bearer ... header on every request. Two token formats are accepted:

• Raw API key (sugra_...) - passed through as the downstream x-api-key. Backward compatible with v0.1.x.
• OAuth JWT - signature verified against the issuer's JWKS. The sub claim identifies the user; the server then looks up that user's primary API key via an internal endpoint on the authorization server.

Variable	Required	Default	Description
SUGRA_APP_URL	HTTP + OAuth	https://app.sugra.ai	Base URL of the authorization server
SUGRA_JWKS_URL	No	$SUGRA_APP_URL/oauth/jwks.json	JWKS endpoint
INTERNAL_API_TOKEN	HTTP + OAuth	-	Shared secret for the user lookup endpoint on the authorization server. Same value must be set on both the MCP process and the app.sugra.ai Laravel process

Examples

Ask Claude:

• "What's Bitcoin's current price and how did it move this week?"
• "Show me Apple's income statement and debt profile."
• "Compare US vs Germany CPI over the last 5 years."
• "What's the Fed funds rate today, and what was the last change?"
• "Find all Sugra endpoints related to shipping or vessels."

Troubleshooting

SUGRA_API_KEY environment variable is required

The server could not find your API key. Depending on how you run it:

• As an MCP tool from your client (Claude, ChatGPT, Gemini, xAI, IDE, etc.): check the env block in your MCP config file. Value should be a full key like sugra_ao1_..., not empty and not wrapped in extra quotes.
• Shell / CI: export SUGRA_API_KEY=sugra_... before running sugra-api-mcp.
• HTTP mode: set via .env or systemd EnvironmentFile, not the shell.

401 Unauthorized or 403 Forbidden in tool responses

Key accepted but rejected. Common causes:

• Key was regenerated in app.sugra.ai/settings/billing and your config still has the old one.
• Typo - key contains only lowercase letters and digits, no spaces, no trailing newlines.
• Free tier was deactivated. Sign in to verify status.

429 Too Many Requests

Hit your plan's daily limit. Response headers include X-RateLimit-Reset with the UTC timestamp when the counter resets (midnight UTC). Upgrade your plan at app.sugra.ai/settings/billing.

Invalid Host header (only if self-hosting HTTP mode)

FastMCP has DNS rebinding protection. Set SUGRA_MCP_ALLOWED_HOSTS to a comma-separated list of the public hostnames your reverse proxy serves. Example: SUGRA_MCP_ALLOWED_HOSTS=mcp.example.com,example.com.

Tool result truncated with meta.truncated notice

Some endpoints return very large payloads (global wildfires, full table catalogs). The client enforces the MCP 25k token limit - when hit, the data list is trimmed and a retry hint appears in meta.truncated.retry_hint. Add narrower filters (country, date range, limit) to get the full result.

Python version 3.13 or higher is required

sugra-api-mcp requires Python 3.13+. Check: python --version. If you have 3.12 or older:

• Ubuntu: sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.13
• macOS: brew install python@3.13
• Windows: download from python.org

Then recreate your venv.

Hosted app.sugra.ai/mcp returns 5xx

The hosted endpoint can briefly restart after deploys. Wait 60 seconds and retry. If persistent, email [e-mail].

Debugging tool calls locally

Run with stdio and log JSON-RPC messages:

SUGRA_API_KEY=sugra_... sugra-api-mcp 2>&1 | tee mcp-debug.log

Send manual JSON-RPC from a second terminal using nc or an MCP inspector.

Development

git clone https://github.com/Sugra-Systems/prod-sugra-ai-MCP
cd prod-sugra-ai-MCP
pip install -e ".[dev,http]"
export SUGRA_API_KEY=sugra_...
python -m sugra_api_mcp  # stdio mode
python -m sugra_api_mcp --transport streamable-http --port 8001  # HTTP mode

Run tests:

pytest

License

MIT © Sugra Systems, Inc.