Sugra API

View saved version →

---
name: auth-and-quota
description: Authenticate to Sugra over HTTPS and MCP and stay inside the daily quota. Use when setting up a client or when a call returns 401, 403, missing_api_key, missing_bearer_token, or 429.
license: MIT
---

# Auth and quota

One key. Two header shapes. Volume gating only: every plan sees every endpoint. Plans and errors on https://docs.sugra.ai (search Authentication, Rate limits).

Issue a key at https://app.sugra.ai/settings/billing. Prefix `sugra_...`. Do not log it.

| Plan | Requests / day |
|---|---|
| Free | 50 |
| Dev | 5,000 |
| Pro | 50,000 |

Some bulk endpoints cost more than 1 request. HTTP reports `X-RateLimit-Cost`. MCP `describe_endpoint` `agent_hints.bulk_cost` warns before the call.

## HTTPS API

```
x-api-key: sugra_...
```

Not `Authorization: Bearer` on `https://sugra.ai`.

Every data response also carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (UTC), `X-RateLimit-Cost`.

## MCP

| Transport | Client auth | Process env |
|---|---|---|
| Hosted `https://mcp.sugra.ai/mcp` | `Authorization: Bearer` (raw key or OAuth JWT) | n/a |
| Local stdio | none on the wire | `SUGRA_API_KEY` in the server process |
| Self-hosted HTTP | client Bearer; process `SUGRA_API_KEY` is only a downstream fallback | |

OAuth JWT: audience `https://app.sugra.ai/mcp` on both MCP hosts, scope `sugra:read`. Hosted discovery is public. `tools/call` and `resources/read` return 401 `missing_bearer_token` without Bearer.

Stdio catalog tools (`search_endpoints`, `describe_endpoint`, `list_toolsets`, `list_sources`) work without a key. `call_endpoint`, `fetch_data`, and entity tools return `missing_api_key` until `SUGRA_API_KEY` is set.

MCP tool JSON does not forward `X-RateLimit-*`. On 429 wait for `retry_after` (seconds). Downstream MCP still calls the API with `x-api-key`.

## Errors

| Signal | Meaning | What to do |
|---|---|---|
| HTTP 401 / MCP `missing_api_key` / `missing_bearer_token` | missing or invalid credential | stop. Do not retry the same call. |
| HTTP 403 | key cannot use this route | stop. |
| HTTP 429 / MCP 429 | quota exhausted | wait until `X-RateLimit-Reset` or `retry_after`. |
| HTTP 5xx / MCP `upstream_*` | platform or upstream fault | retry once with backoff. Then report. |

Do not retry 4xx except 429 after the reset.

Referenced files: 1

View saved version →

---
name: connect
description: Attach a client to Sugra over HTTPS or MCP. Use when setting up Claude Desktop, Claude Code, ChatGPT, claude.ai, Cursor, VS Code, Gemini CLI, Grok, OpenBB, a custom HTTP agent, or self-hosted MCP.
license: MIT
---

# Connect

Same key for every path: https://app.sugra.ai/settings/billing, prefix `sugra_...`. Do not log it. Client JSON blocks: [references/clients.md](references/clients.md).

## 1. HTTPS API

```
GET https://sugra.ai/api/v1/...
x-api-key: sugra_...
```

System endpoints (`/health`, `/about`, `/services`, `/sources`, `/openapi.json`) need no key. Recipes: https://github.com/Sugra-Systems/sugra-api-cookbook. Endpoint detail: https://docs.sugra.ai.

## 2. Hosted MCP

Canonical: `https://mcp.sugra.ai/mcp`
Permanent alias: `https://app.sugra.ai/mcp`

Auth: `Authorization: Bearer sugra_...` or OAuth (audience `https://app.sugra.ai/mcp`, scope `sugra:read`). Discovery is public. `tools/call` and `resources/read` need Bearer.

claude.ai: Settings -> Connectors -> Add custom connector.
ChatGPT: install skills from the Plugins Directory (https://chatgpt.com/plugins/plugins_6aa4f7db79848191a81e4048990545ef). Hosted MCP tools: Settings -> Connectors -> Add MCP server.

Hosted tools: 8 gateway plus 3 composed (`resolve_entity`, `get_snapshot`, `get_timeseries`). Confirm with live `tools/list`.

## 3. Local MCP stdio

```bash
pip install sugra-api-mcp
export SUGRA_API_KEY=sugra_...
```

Eight gateway tools. Catalog search works without the key; `call_endpoint` / `fetch_data` / entity tools return `missing_api_key` until it is set. If the console script is not on PATH: `"command": "python", "args": ["-m", "sugra_api_mcp"]`.

Package CLI: `sugra-api-mcp doctor`, `search`, `describe`, `call`.

Claude Desktop, Claude Code, Gemini CLI, Cursor, VS Code, and similar IDEs use the stdio block in [references/clients.md](references/clients.md), or the hosted URL with Bearer.

## 4. Self-hosted MCP HTTP

```bash
sugra-api-mcp --transport streamable-http --port 8001
```

Eight tools, not the hosted-only three. Operator CORS/host/OAuth: `docs/self-hosting.md` in `sugra-api-mcp`. Do not put `INTERNAL_API_TOKEN` or JWKS URLs in a skill or chat.

## 5. OpenBB

Public extension `openbb-sugra` uses the HTTPS API, not MCP.

## Pick

| Host | Typical attach |
|---|---|
| Script, custom agent, OpenBB | HTTPS `x-api-key` |
| ChatGPT | Plugins Directory listing plus hosted MCP |
| claude.ai | Hosted MCP connector |
| Claude Desktop / Code, Cursor, VS Code, Gemini CLI, Grok | stdio package or hosted MCP |
| Own HTTP MCP process | self-host |

Referenced files: 2

View saved version →

---
name: cross-domain-briefing
description: Compose one briefing from two or three Sugra directions over HTTPS or MCP. Use when a question spans Finance, Macro, Entity, Net Atlas, News, Earth, or Research and one operation is not enough.
license: MIT
---

# Cross-domain briefing

Split the question. Call two or three operations. Do not invent a combined index. HTTP and MCP are both valid; use the surface already connected (skill `connect`). Confirm each operation on https://docs.sugra.ai.

## Pattern

1. Split the question into 2-3 concrete asks (place, series, snapshot). Name the directions involved (Finance, Macro, Entity, Net Atlas, News, Earth, Research).
2. For each ask, discover then call (`discover-and-call`). Prefer sovereign or intergovernmental sources when the catalog offers them.
3. Keep units, geography, and clocks separate. Do not blend a port throughput z-score with a weather reading into one invented number.
4. Quote each figure with its source from `meta` and its `as_of` / `meta.data_time`.
5. Close with what the catalog did not cover, not a prediction.

## Example shape (not a canned path list)

"What is happening around a chokepoint this week?" can be three calls: port throughput (Sugra Earth / transport), conditions at a coordinate on the route (Sugra Earth), and one related sovereign or intergovernmental series docs.sugra.ai actually lists. Discover, call, present side by side.

The MCP prompt `earth_conditions` is a one-coordinate weather recipe. This skill is the longer form when weather is only one pane.

Do not add per-endpoint MCP tools. Do not treat screening as a briefing source unless the question is about a named party. Do not call hosted-only MCP tools on stdio. Do not frame the output as investment, legal, or routing advice.

Referenced files: 1

View saved version →

---
name: discover-and-call
description: Find the right Sugra operation and call it over HTTPS or MCP. Use when the path or operation_id is unknown, before guessing parameters, or after a catalog miss. Confirm details on https://docs.sugra.ai. Do not invent routes.
license: MIT
---

# Discover and call

Do not invent paths or `operation_id`s. Confirm the operation on https://docs.sugra.ai (search or Ask AI, then the endpoint page). Two complete loops, same API.

## HTTP loop

1. If the path is already known, skip to step 4 after confirming it on docs.sugra.ai.
2. Search https://docs.sugra.ai. Machine companion: `GET https://sugra.ai/openapi.json`. Coarse map: `GET /services`, `GET /sources`.
3. Read parameters and, for POST, the request body. Required names come from docs or the spec.
4. Call `https://sugra.ai` with `x-api-key`. GET uses query params. POST uses JSON body plus any path or query params the spec lists.
5. Parse `{data, meta}`. Cite source and `data_time`. Read `X-RateLimit-Remaining`.

```
GET https://sugra.ai/api/v1/etf/sectors/relative-strength?window=1m
x-api-key: sugra_...
```

## MCP loop

Works on hosted (11 tools) and stdio (8 tools). Do not call hosted-only names on stdio.

1. `search_endpoints(query=..., toolset=None, source=None, limit=10)`. Unknown `toolset` / `source` returns `unknown_toolset` / `unknown_source` with the valid set, not an empty hit list.
2. Pick an `operation_id` from `results`. Confirm it on docs.sugra.ai.
3. `describe_endpoint(operation_id=...)` - params, `request_body_schema` on POST, `agent_hints` (`duration_class`, `max_concurrency`, `bulk_cost`).
4. `call_endpoint(operation_id=..., params={...}, body=...)`.

`fetch_data(query=...)` is a one-shot. If it misses, use the four-step loop. `list_toolsets` and `list_sources` (resources `sugra://catalog/domains`, `sugra://catalog/sources`) are the map, not the query.

Shaping on `call_endpoint` / `fetch_data`: `limit`, `fields` (dotted paths), `include_raw`. `limit` bounds only the top-level list. `meta.shaped` reports what applied.

Hosted only: `resolve_entity`, `get_snapshot`, `get_timeseries`. LEI/VAT and sanctions on every transport: `sugra_entity_lookup`, `sugra_entity_screen`.

Six MCP prompts (`market_snapshot`, `macro_briefing`, `sanctions_screening`, `sector_compare`, `earth_conditions`, `source_overview`) are recipes over the eight gateway tools. They are not the catalog.

## Misses

A miss is not "Sugra has no data". Search docs.sugra.ai. Widen the query. Drop a bad MCP `toolset`/`source` filter. If MCP search still misses, fetch live `/openapi.json` (the wheel catalog can lag), then HTTP-call if the spec has it.

Do not add per-endpoint MCP tools to skip this loop.

## Timeouts

30 seconds covers most GETs. Bulk or live-upstream POSTs can run longer. MCP `agent_hints.duration_class` is the budget hint. A timeout is not empty data.

Referenced files: 1

View saved version →

---
name: envelope-and-attribution
description: Parse Sugra API payloads over HTTPS or MCP, keep source attribution, and tell observation time from request time. Use when reading a response, citing a figure, or shaping a large payload.
license: MIT
---

# Envelope and attribution

The API is LLM-friendly: one JSON envelope on every direction. Envelope detail also lives on https://docs.sugra.ai.

Most responses:

```json
{
  "data": {},
  "meta": {
    "endpoint": "/api/v1/...",
    "data_time": "2026-06-12T19:30:00Z",
    "response_time": "2026-06-12T19:30:01Z",
    "provider": "Sugra API"
  }
}
```

Some payloads are envelope-less (a flat object with `meta` or `_meta` on the same record). Provenance keys still apply.

HTTP: this JSON body plus `X-RateLimit-*` headers.

MCP: `call_endpoint` / `fetch_data` return the same payload (a top-level array is wrapped as `{data: ...}`). Shaping args `limit`, `fields`, `include_raw` apply to `data`. `meta.shaped` reports `fields_applied`, `fields_unmatched`, `limit_applied`. `limit` bounds only the top-level list.

## Time

`meta.data_time` is the observation or publication clock of the data, not the HTTP response time. A row-level `as_of` is the period the figure is about. Quote both when they differ. Do not describe a delayed series as a live tick.

## Attribution

Every figure needs a source and an as-of. Read them from `meta` / `_meta`. Live list: https://sugra.ai/sources (MCP resource `sugra://attribution`).

- Sovereign, intergovernmental, and academic sources are named openly (for example FRED, IMF, ECB, NOAA, World Bank, SEC EDGAR).
- Commercial upstreams appear under Sugra-branded wrappers (Sugra Finance, Sugra News, Sugra Crypto, Sugra Forex, Sugra Weather). Do not substitute a commercial vendor name.

This is data presentation, not investment, legal, or compliance advice. Screening tools return a signal, not a determination.

Referenced files: 1

View saved version →

---
name: live-docs
description: Find current Sugra documentation. Use when an endpoint, parameter, count, or version might be stale. Canonical docs are https://docs.sugra.ai (search and Ask AI). Also OpenAPI, /sources, /stats, the blog, and MCP tools/list.
license: MIT
---

# Live docs

https://docs.sugra.ai is the external documentation truth. It has search and Ask AI. Per-endpoint parameters, schemas, and examples live in its API Reference sidebar. This skill pack does not copy that catalog.

Entry on the API host: https://sugra.ai/docs (same site). Do not use `https://sugra.ai/doc`.

## How to read docs.sugra.ai

1. Open https://docs.sugra.ai (Welcome: directions, key, envelope, plans, MCP).
2. Search the docs site, or use Ask AI, for the operation or topic.
3. Open the endpoint page in API Reference before calling. Confirm method, path, parameters, and body.
4. If a page offers a Markdown view or `.md` URL, prefer that for a compact read.

Do not invent a path. Do not treat this SKILL.md, a README, or a cookbook recipe as the operation list.

## Machine companions (not a second docs site)

| URL | Role |
|---|---|
| `GET https://sugra.ai/openapi.json` | HTTP contract for the call |
| `GET https://sugra.ai/sources` | live source families |
| `GET https://sugra.ai/services` | service list |
| `GET https://sugra.ai/about` | product surface |
| `GET https://sugra.ai/health` | liveness |
| `GET https://sugra.ai/stats` | live counts |

Public copy still uses hedges (1,500+ / 160+ / 36). `/stats` is the live counter. The MCP wheel catalog can lag OpenAPI. If MCP search misses, search docs.sugra.ai, then OpenAPI, then say whether the operation exists.

MCP after connect: `initialize` (`serverInfo.version`), `tools/list`, `prompts/list`, `resources/list`.

## Other public surfaces (search these, not the open web first)

| Where | What |
|---|---|
| https://sugra.ai | product |
| https://sugra.systems | company, legal, API marketing, direction pages |
| https://sugra.systems/blog | blog index; article also as `/{slug}.md`; `llms.txt` |
| https://app.sugra.ai | keys, billing, playground |
| https://app.sugra.ai/settings/billing | issue a key |
| https://pypi.org/project/sugra-api-mcp/ | MCP package version |
| https://github.com/Sugra-Systems/sugra-api-mcp | MCP server |
| https://github.com/Sugra-Systems/sugra-api-cookbook | HTTP recipes |
| https://github.com/Sugra-Systems/openbb-sugra | OpenBB provider |

Legal: https://sugra.systems/terms-of-service and sibling policy pages. Contacts: `support@`, `legal@`, `privacy@`, `abuse@` sugra.systems.

Source names: live `/sources`. Sovereign, intergovernmental, and academic names are open. Commercial upstreams appear as Sugra Finance, Sugra News, Sugra Crypto, Sugra Forex, Sugra Weather.

Referenced files: 1

View saved version →

---
name: using-sugra-api
description: Work with the Sugra API over HTTPS and MCP. Use when the task needs Sugra data, a key, product directions (Finance, Macro, Entity, Net Atlas, News, Earth, Research), or which skill to load next.
license: MIT
---

# Using the Sugra API

Sugra API is intelligence infrastructure: one HTTP API, one key, seven product directions. Domain-agnostic. Do not frame it through one vertical.

The surface is LLM-friendly: one `x-api-key`, one JSON envelope `{data, meta}` on every direction, MCP as the agent-native entry. Documentation truth is https://docs.sugra.ai (search and Ask AI). This skill is a map, not the catalog.

These files are English. Reply in the user's language.

Public hedge (not a live count): 1,500+ endpoints, 160+ primary sources, 36 domains. Live counts: skill `live-docs`.

## Two complete ways in

| Surface | When | How |
|---|---|---|
| HTTPS `https://sugra.ai` | The agent can GET/POST | `x-api-key` on `/api/v1/...` |
| MCP | The host is an MCP client | hosted `https://mcp.sugra.ai/mcp` or local `sugra-api-mcp` |

Both reach the same API. Use the surface the host already has, or the one the user named. Key: https://app.sugra.ai/settings/billing (Free: 50 requests/day). Do not log the key.

## Seven directions (one key, one budget)

| Direction | Coverage |
|---|---|
| Sugra Finance | Equities, fundamentals, filings, fixed income, derivatives, crypto, forex |
| Sugra Macro | Central banks, national statistics, FRED, IMF, World Bank, OECD |
| Sugra Entity | Company resolution, sanctions and watchlist screening, identifiers |
| Sugra Net Atlas | Internet infrastructure: ASNs, prefixes, IXPs, routing, DNS |
| Sugra News | Global news flow and event signals |
| Sugra Earth | Weather, hazards, energy, transport, air quality, climate |
| Sugra Research | Scientific, patent, and academic datasets |

## Skill map

| Need | Skill |
|---|---|
| Live docs, search, Ask AI, sources, blog | `live-docs` |
| Attach HTTP, hosted MCP, stdio, self-host, each client | `connect` |
| Key, plans, 401/429, Bearer vs `x-api-key` | `auth-and-quota` |
| Find and call an operation (HTTP and MCP) | `discover-and-call` |
| Envelope, sources, clocks, MCP shaping | `envelope-and-attribution` |
| Two or three directions in one answer | `cross-domain-briefing` |

Referenced files: 1