[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_114":115},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module '@sugra-systems/prod-sugra-ai-mcp' is not configured","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":26,"_34":-5,"_35":36,"_37":-5,"_38":-5,"_39":40,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":48,"_56":57,"_58":59,"_60":61,"_62":63,"_64":65,"_66":48,"_67":68,"_69":70,"_71":72,"_73":74,"_75":76,"_77":-5,"_78":-5,"_79":-5,"_80":48,"_81":-5,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93,"_94":95},"apiUrl","https://odel.app/api","creator","sugra-systems","moduleId","prod-sugra-ai-mcp","@sugra-systems/prod-sugra-ai-mcp","displayName","Sugra API","tagline","Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.","iconKey","https://avatars.githubusercontent.com/u/115420478?v=4","category","data","status","published","metaDescription","metaKeywords","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://app.sugra.ai/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1781363369000,"updatedAt",1781756423000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Sugra-Systems%2Fsugra-api-mcp","sourceVerified",true,"importedAt","upstreamStars",1,"upstreamUpdatedAt",1781695301000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt","githubRepoUrl","https://github.com/Sugra-Systems/prod-sugra-ai-MCP","githubRepoFullName","Sugra-Systems/prod-sugra-ai-MCP","releaseId","ext-sugra-systems-prod-sugra-ai-mcp","version","0.8.0","descriptionMarkdown","# sugra-api-mcp\n\n\n\n

\n $\"sugra.ai\"$ \n

\n\n

\n PyPI v0.8.0 |\n Python 3.11+ |\n MIT\n

\n\n**Gateway connector between LLM agents and world data.** Official [Model Context Protocol](https://modelcontextprotocol.io) server for the [Sugra API](https://sugra.ai), backed by a bundled endpoint catalog and operation_id calls.\n\nWorks with Anthropic Claude, OpenAI GPT, Google Gemini, xAI, and any MCP-enabled IDE.\n\nClient details:\n\n- **Anthropic Claude**: Claude Desktop, Claude Code (CLI), claude.ai (web)\n- **OpenAI GPT**: ChatGPT (via MCP connector)\n- **Google Gemini**: Gemini CLI, Gemini Code Assist (VS Code + JetBrains)\n- **xAI**: Remote MCP Tools in xAI SDK and Responses API\n- **IDEs**: VS Code (native), Cursor, Zed, Cline, Continue.dev, Windsurf\n- **Custom agents**: anything built on the Python or TypeScript MCP SDK\n\n## What you get\n\nCurrent release: eight-tool surface with hosted OAuth activity validation for `https://app.sugra.ai/mcp`, plus ChatGPT Apps-compatible OAuth tool metadata. Curated tool names such as `get_market_price`, `get_macro_indicator`, and `get_news` are not part of this package. The package exposes exactly eight tools:\n\n| Tool | Purpose |\n|---|---|\n| `fetch_data` | One-step: find best endpoint for a natural-language query and call it. Combines search + call in one round trip. |\n| `search_endpoints` | Search the bundled endpoint catalog. Runtime search does not fetch `/openapi.json`. |\n| `describe_endpoint` | Inspect an endpoint by `operation_id`, including path, method, parameters, required inputs, `agent_hints`, and `request_body_schema` for JSON-body POST operations. |\n| `call_endpoint` | Call a Sugra API operation by `operation_id`. Arbitrary path calls are no longer supported. |\n| `list_toolsets` | List catalog groups with endpoint counts and descriptions. |\n| `list_sources` | Show bundled catalog source metadata. |\n| `sugra_entity_screen` | Screen a name against sanctions and watchlists (Sugra Entity). |\n| `sugra_entity_lookup` | Composed entity lookup by identifier - `anchor` is `lei` or `vat`, plus the identifier `value`; returns registry identity + screening (Sugra Entity). |\n\n`call_endpoint` and `fetch_data` both support response shaping with `limit`, `fields`, and `include_raw`. Shaping works on enveloped (`{\"data\": ...}`) and envelope-less payloads alike; `fields` entries may use dotted paths into nested objects (`geo.city`), and `meta.shaped` reports what was actually applied (`fields_applied` / `fields_unmatched`, `limit_applied`) rather than echoing the request.\n\n`describe_endpoint` returns computed `agent_hints` per endpoint so agents can budget time and parallelism before calling:\n\n- `duration_class` - `fast` (under ~2s, snapshot-backed), `slow` (live upstream proxying, occasionally 15s+), or `heavy` (per-item upstream work, large batches can exceed the gateway timeout)\n- `max_concurrency` - advisory ceiling for parallel calls from one session\n- `bulk_cost` - on per-item bulk endpoints: 1 request credit per item in the request body (the API reports the total in the `X-RateLimit-Cost` response header)\n\n## Hosted-only agent tools (app.sugra.ai/mcp)\n\nThe hosted MCP endpoint at `https://app.sugra.ai/mcp` serves the same eight tools PLUS three composed agent tools that are not available on stdio or self-hosted installs:\n\n| Tool | Purpose |\n|---|---|\n| `resolve_entity` | Free text (ticker, company, indicator, coin, currency pair) to a canonical market or macro entity. Ambiguous matches return ranked candidates, never a silent pick. |\n| `get_snapshot` | Entity plus a named recipe to one composed current view with freshness, provenance, coverage, and billing blocks. Composed calls charge a fixed recipe cost (1-2 requests) from the daily quota. |\n| `get_timeseries` | Entity plus metric (`price`, `macro_series`, `etf_flows`) to a bounded series with an explicit downsampling flag. |\n\nThese three tools wrap an internal composed plane that requires an infrastructure credential available only on the hosted deployment. The tool code ships inside the package, but it is registered only by the hosted HTTP entry point and only when that credential is present - `pip install sugra-api-mcp` (stdio and self-hosted HTTP) always exposes the classic eight-tool gateway. Hosted-only examples in any documentation are labeled as such. For compliance entity lookups (LEI / VAT, sanctions screening) use `sugra_entity_lookup` and `sugra_entity_screen`, which work on every transport.\n\n## Installation\n\n```bash\npip install sugra-api-mcp\n```\n\nGet a free API key at [app.sugra.ai/settings/billing](https://app.sugra.ai/settings/billing) (Free tier: 50 req/day).\n\n## Usage with Claude Desktop (stdio)\n\nAdd to `claude_desktop_config.json`:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: Claude Desktop has no Linux build. On Linux, `pip install sugra-api-mcp` and use Claude Code (CLI), an IDE client, or the hosted HTTP endpoint below.\n\n```json\n{\n \"mcpServers\": {\n \"sugra\": {\n \"command\": \"sugra-api-mcp\",\n \"env\": {\n \"SUGRA_API_KEY\": \"sugra_xxx_yourkey...\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop. Sugra tools appear in the tools menu.\n\n## Usage with Claude Code (Anthropic CLI)\n\n```bash\nclaude mcp add sugra -- sugra-api-mcp\n# then set the env var that sugra-api-mcp reads\nexport SUGRA_API_KEY=sugra_xxx_...\n```\n\nOr edit `~/.claude/config.json` manually with the same shape as Claude Desktop above.\n\n## Usage with Cursor, Zed, Cline, Continue.dev, Windsurf\n\nEach of these has an MCP settings file (typically `mcp.json` or equivalent) with the same stdio config shape as Claude Desktop.\n\n## Usage with ChatGPT\n\nChatGPT supports MCP through its connector UI. Use the hosted HTTP endpoint (below) since ChatGPT does not launch local stdio processes.\n\n## Usage over HTTP (claude.ai, ChatGPT, remote agents)\n\nHosted Streamable HTTP endpoint:\n\n```\nhttps://app.sugra.ai/mcp\n```\n\nAdd to claude.ai, ChatGPT, or any Streamable HTTP MCP client. Authenticate with `Authorization: Bearer sugra_xxx_...`.\n\nIn claude.ai: Settings -> Connectors -> Add custom connector.\nIn ChatGPT: Settings -> Connectors -> Add MCP server.\n\n## CLI\n\nServer startup is unchanged:\n\n```bash\nsugra-api-mcp\nsugra-api-mcp --transport streamable-http --port 8001\n```\n\nCatalog and gateway helpers:\n\n```bash\nsugra-api-mcp doctor\nsugra-api-mcp list-toolsets\nsugra-api-mcp search \"NASDAQ futures\"\nsugra-api-mcp describe cot_financial\nsugra-api-mcp call quotes_symbol_price --params '{\"symbol\":\"AAPL\"}'\n```\n\n## Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `SUGRA_API_KEY` | Yes (stdio) | - | Your Sugra API key. In HTTP mode with OAuth this becomes a fallback for requests without Bearer |\n| `SUGRA_API_BASE` | No | `https://sugra.ai` | Override for self-hosted or beta environments |\n| `SUGRA_TIMEOUT` | No | `30` | Request timeout in seconds |\n| `SUGRA_MCP_ALLOWED_HOSTS` | No (HTTP) | - | Comma-separated hostnames to allow behind a reverse proxy |\n| `SUGRA_MCP_ALLOWED_ORIGINS` | No (HTTP) | chatgpt.com, claude.ai, cursor.sh + others | Comma-separated allowed Origins for browser-based MCP clients. Applies to BOTH the outer Starlette CORS layer and the inner FastMCP DNS rebinding Origin check, so the two stay in sync. `*` disables the inner Origin check entirely (self-hosted / dev only); Bearer auth still gates tool calls |\n\n### HTTP transport with OAuth\n\nWhen running with `--transport streamable-http` the server allows unauthenticated MCP discovery requests (`initialize`, `notifications/initialized`, `tools/list`, `resources/list`, `prompts/list`, and `ping`) so ChatGPT Apps and other mixed-auth clients can discover tool metadata. CORS is enabled for major MCP clients (ChatGPT, Claude, Cursor) so browser connector UIs can complete the OAuth flow; override the allowlist with `SUGRA_MCP_ALLOWED_ORIGINS`. Tool calls still require `Authorization: Bearer ...`. Two token formats are accepted:\n\n- Raw API key (`sugra_...`) - passed through as the downstream `x-api-key`. Compatible with earlier local API-key setups.\n- OAuth JWT - signature verified against the issuer's JWKS. The audience must match `https://app.sugra.ai/mcp`, the token must include `sugra:read`, and hosted access is validated against APP before resolving the user's primary API key. Successful hosted OAuth requests update MCP connection activity in APP.\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `SUGRA_APP_URL` | HTTP + OAuth | `https://app.sugra.ai` | Base URL of the authorization server |\n| `SUGRA_JWKS_URL` | No | `$SUGRA_APP_URL/oauth/jwks.json` | JWKS endpoint |\n| `INTERNAL_API_TOKEN` | HTTP + OAuth | - | Shared secret for the user lookup and MCP activity endpoints on the authorization server. Same value must be set on both the MCP process and the app.sugra.ai Laravel process |\n\n## Timeouts and the error contract\n\n`SUGRA_TIMEOUT` caps each downstream HTTP call from this server to the Sugra API (default 30 seconds). It is one link in a longer chain; when a tool call fails, `elapsed_ms` in the error payload tells you which link cut it:\n\n```\nMCP client (agent harness) own tool timeout, often 60-180s, client-controlled\n -> hosted proxy (app.sugra.ai) 86400s, effectively unlimited\n -> this server (httpx) SUGRA_TIMEOUT, default 30s\n -> Sugra API -> upstreams 15-60s per upstream call, server-side\n```\n\nTool failures return structured JSON instead of raising, so agents can pick a retry strategy:\n\n| `error` value | Meaning | Retry strategy |\n|---|---|---|\n| `upstream_timeout` | No response within `SUGRA_TIMEOUT` (`elapsed_ms` close to `timeout_s` x 1000) | Retry once: the aborted attempt usually completes server-side and warms upstream caches. Then narrow the request (smaller batch, tighter filters). |\n| `upstream_connect_error` | Could not reach the Sugra API (DNS failure, connection refused) | Retry after a short delay. |\n| `upstream_transport_error` | Connection dropped mid-request | Retry once. |\n| free-text string + `status_code` | The API answered with HTTP 4xx/5xx; `retry_after` included when the API sent a Retry-After header | Honor `retry_after` for 429/503; fix the request for 4xx. |\n| `tool_execution_failed` | Unexpected failure inside the gateway (`exception_type` included) | Report if persistent. |\n\nAll error payloads carry `elapsed_ms`. `url` is present on transport and HTTP errors (not on `tool_execution_failed`, which can fire before a URL exists). On the three transport errors `status_code` is `null` (no HTTP status was received) - consumers comparing `status_code` numerically should guard for that. If a tool call instead fails with a bare client-side message and no structured JSON, the timeout fired in your agent harness above this server: raise the client's tool timeout, not `SUGRA_TIMEOUT`.\n\n## Examples\n\nAsk Claude:\n\n- \"Search Sugra endpoints for NASDAQ futures.\"\n- \"Describe the `cot_financial` operation.\"\n- \"Call `quotes_symbol_price` with symbol AAPL and return only symbol and price.\"\n- \"List available Sugra toolsets.\"\n\n## Troubleshooting\n\n**`SUGRA_API_KEY environment variable is required`**\n\nThe server could not find your API key. Depending on how you run it:\n- 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.\n- Shell / CI: `export SUGRA_API_KEY=sugra_...` before running `sugra-api-mcp`.\n- HTTP mode: set via `.env` or systemd `EnvironmentFile`, not the shell.\n\n**`401 Unauthorized` or `403 Forbidden` in tool responses**\n\nKey accepted but rejected. Common causes:\n- Key was regenerated in [app.sugra.ai/settings/billing](https://app.sugra.ai/settings/billing) and your config still has the old one.\n- Typo - key contains only lowercase letters and digits, no spaces, no trailing newlines.\n- Free tier was deactivated. Sign in to verify status.\n\n**`429 Too Many Requests`**\n\nHit 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](https://app.sugra.ai/settings/billing).\n\n**`Invalid Host header`** (only if self-hosting HTTP mode)\n\nFastMCP 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`.\n\n**Tool result truncated with `meta.truncated` notice**\n\nSome 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.\n\n**`Python version 3.11 or higher is required`**\n\nsugra-api-mcp requires Python 3.11+. Check: `python --version`. If you have 3.10 or older:\n- Ubuntu: install Python 3.11 or newer from your distribution packages or the deadsnakes PPA.\n- macOS: `brew install python@3.11`\n- Windows: download from [python.org](https://www.python.org/downloads/)\n\nThen recreate your venv.\n\n**Hosted `app.sugra.ai/mcp` returns 5xx**\n\nThe hosted endpoint can briefly restart after deploys. Wait 60 seconds and retry. If persistent, email support@sugra.systems.\n\n**Debugging tool calls locally**\n\nRun with stdio and log JSON-RPC messages:\n```bash\nSUGRA_API_KEY=sugra_... sugra-api-mcp 2>&1 | tee mcp-debug.log\n```\nSend manual JSON-RPC from a second terminal using `nc` or an MCP inspector.\n\n## Development\n\n```bash\ngit clone https://github.com/Sugra-Systems/prod-sugra-ai-MCP\ncd prod-sugra-ai-MCP\npip install -e \".[dev,http]\"\nexport SUGRA_API_KEY=sugra_...\npython -m sugra_api_mcp # stdio mode\npython -m sugra_api_mcp --transport streamable-http --port 8001 # HTTP mode\npython scripts/build_endpoint_catalog.py # rebuild bundled catalog from sibling API openapi.json\n```\n\nRun tests:\n\n```bash\npytest\n```\n\n## License\n\nMIT © 2026 Sugra Systems, Inc.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Data & Analytics","upstream",{"_98":99,"_100":101,"_102":103,"_104":105,"_106":107},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_96":83,"_97":83},"ratingAvg","reviewCount","topics",[108,109,110,111,112,113],"license","MIT","language","Python","registryName","io.github.Sugra-Systems/sugra-api-mcp","homepage","https://sugra.ai","data-platform","intelligence-infrastructure","llm-tools","mcp","model-context-protocol","python","ENV",{"_116":117,"_118":119,"_120":121},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]