> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gildea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Gildea to Claude Code, Cursor, and other MCP clients

Gildea provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server so AI assistants can use Gildea's verified intelligence as a tool. We host it publicly at **`https://api.gildea.ai/mcp/`**.

It speaks the streamable-HTTP MCP transport and auths via the `x-api-key` header. Most clients let you paste these two values (URL + key) and you're done.

### Claude Code

```bash theme={null}
claude mcp add gildea --transport http https://api.gildea.ai/mcp/ --header "x-api-key: gld_your_key_here"
```

Verify with `claude mcp list`; you should see `gildea ✓ Connected` with 7 tools. To avoid hardcoding the key, use `--header "x-api-key: ${env:GILDEA_API_KEY}"`.

### Cursor

Add Gildea to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):

```json theme={null}
{
  "mcpServers": {
    "gildea": {
      "url": "https://api.gildea.ai/mcp/",
      "headers": { "x-api-key": "gld_your_key_here" }
    }
  }
}
```

Gildea's 7 tools then appear in Cursor's MCP settings.

### Other MCP clients

Any client that supports remote, streamable-HTTP MCP servers with custom headers can connect with the same two values (URL + key). Common config shape:

```json theme={null}
{
  "type": "http",
  "url": "https://api.gildea.ai/mcp/",
  "headers": { "x-api-key": "gld_your_key_here" }
}
```

See the [MCP client list](https://modelcontextprotocol.io/clients) for per-client syntax (VS Code via Cline or Continue, and others).

### Claude Desktop

Not supported yet. Claude Desktop's config file does not read custom headers for remote MCP servers, and its Connectors UI accepts only OAuth, so an API-key server like Gildea cannot connect there today. Use Claude Code or Cursor for now. Claude Desktop support will follow if it adds custom-header auth (or once Gildea offers OAuth).

## REST API vs MCP

Both access the same data. Choose based on your use case.

|                 | REST API                                   | MCP Server                          |
| --------------- | ------------------------------------------ | ----------------------------------- |
| **Best for**    | Apps, dashboards, pipelines, custom agents | Claude Code, Cursor, any MCP client |
| **Protocol**    | HTTP/JSON                                  | streamable-HTTP (remote)            |
| **Auth**        | `X-API-Key` header                         | `x-api-key` header                  |
| **Rate limits** | Shared quota                               | Shared quota                        |
| **Pagination**  | Cursor-based                               | Cursor-based                        |
| **Data**        | Identical                                  | Identical                           |

Rate limits are shared across REST and MCP. A request from an MCP client and a request from your app count toward the same per-minute and monthly quota.

## Available tools

The MCP server exposes 7 tools that mirror the REST API.

### `search_text_units`

Search across Gildea's verified text units: thesis, synopsis, and argument sentences, plus atomic claims. Every unit has been verified against source evidence.

Two modes:

* **`q`**: free-text search. Returns the most relevant units across the corpus.
* **`similar_to`**: pass a text unit ID; returns the most similar units (useful for cross-source corroboration and "find more like this").

Exactly one of `q` or `similar_to` is required.

**Parameters:**

| Param              | Type    | Required                  | Description                                                                                     |
| ------------------ | ------- | ------------------------- | ----------------------------------------------------------------------------------------------- |
| `q`                | string  | One of `q` / `similar_to` | Free-text search query                                                                          |
| `similar_to`       | string  | One of `q` / `similar_to` | Text unit ID; finds the most similar units                                                      |
| `role`             | string  | No                        | Filter: `thesis`, `synopsis`, `argument`, or `claim`                                            |
| `entity`           | string  | No                        | Entity public ID (e.g. `gld:/a1b2c3d4e5f6`). Returns only units literally mentioning the entity |
| `theme`            | string  | No                        | Theme label (1 of 12). Returns units from articles tagged with that theme                       |
| `published_after`  | string  | No                        | ISO 8601 date; only results from articles published after this date                             |
| `published_before` | string  | No                        | ISO 8601 date; only results from articles published before this date                            |
| `window`           | string  | No                        | Relative time shortcut (e.g. `7d`, `2w`, `1m`)                                                  |
| `recency_boost`    | number  | No                        | 0.0-1.0. Soft preference for newer results; default 0 (off)                                     |
| `diversity_cap`    | integer | No                        | Max units per source article (1-100, default 2)                                                 |
| `limit`            | integer | No                        | Max results (default 10, max 100)                                                               |

**Example prompt:** *"Search for verified claims about GPU supply constraints"*

```json theme={null}
// Keyword search
{ "q": "GPU supply constraints", "role": "claim", "limit": 5 }
```

**Example prompt:** *"Find text units similar to this claim"*

```json theme={null}
// Similar-to search
{ "similar_to": "0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9", "limit": 5 }
```

### `list_signals`

Find intelligence signals about the AI economy from 500+ expert sources. Each signal is a structured analysis or event report decomposed into verified components; use `get_signal_detail` to access the full tree. All filters are optional; without filters, returns the most recent signals.

**Parameters:**

| Param              | Type    | Required | Description                                                          |
| ------------------ | ------- | -------- | -------------------------------------------------------------------- |
| `entity`           | string  | No       | Entity ID filter                                                     |
| `theme`            | string  | No       | Theme label filter                                                   |
| `keyword`          | string  | No       | Literal keyword filter on title + unit text                          |
| `content_type`     | string  | No       | `analysis` or `event`                                                |
| `published_after`  | string  | No       | ISO date (e.g. `2026-02-01`)                                         |
| `published_before` | string  | No       | ISO date                                                             |
| `window`           | string  | No       | Relative time shortcut (e.g. `7d`, `2w`, `1m`)                       |
| `sort`             | string  | No       | `published` (default) or `changed` (change feed; page with `cursor`) |
| `cursor`           | string  | No       | Opaque cursor from a previous response; pages the change feed        |
| `limit`            | integer | No       | Max results (default: 25, max: 50)                                   |

**Example prompt:** *"Show me recent analysis signals about OpenAI"*

```json theme={null}
{ "entity": "gld:/e5f6a7b8c9d0", "content_type": "analysis", "limit": 5 }
```

### `get_signal_detail`

Get the full verified breakdown of a signal as a flat `units[]` list. This is where Gildea's value lives. Each unit carries a `role`: `thesis`/`synopsis` (the central statement), `argument` (supporting analysis sentences; group by `argument_id` to reconstruct each as a paragraph), and `claim` (atomic facts). Every unit has been independently verified against source evidence, which is included by default. Use this tool liberally; it's the difference between showing metadata and showing actual verified intelligence.

**Parameters:**

| Param       | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `signal_id` | string | Yes      | Signal ID   |

**Example prompt:** *"Get the full verified breakdown of that signal"*

```json theme={null}
{ "signal_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7" }
```

### `list_entities`

Discover which companies, people, and models are getting expert attention in the AI economy. Filter by trend direction, notability, coverage scale, and more. Use this for discovery: finding what's worth paying attention to.

**Parameters:**

| Param        | Type    | Required | Description                                           |
| ------------ | ------- | -------- | ----------------------------------------------------- |
| `name`       | string  | No       | Filter by entity name (substring match)               |
| `theme`      | string  | No       | Filter by theme label                                 |
| `type`       | string  | No       | Filter by entity type                                 |
| `sort`       | string  | No       | `signal_count` (default), `first_seen`, or `trend`    |
| `direction`  | string  | No       | `Rising`, `Stable`, `Declining`, `New`                |
| `confidence` | string  | No       | `Significant`, `Insignificant`                        |
| `stability`  | string  | No       | `Volatile`, `Steady`                                  |
| `scale`      | string  | No       | `Large`, `Medium`, `Small`                            |
| `notability` | string  | No       | `High`, `Medium`, `Low`, `Negligible`                 |
| `cursor`     | string  | No       | Opaque cursor from a previous response for pagination |
| `limit`      | integer | No       | Max results (default: 25, max: 50)                    |

**Example prompt:** *"Show me reliably rising entities"*

```json theme={null}
{ "direction": "Rising", "confidence": "Significant", "sort": "trend", "limit": 10 }
```

### `get_entity_profile`

Get an intelligence profile for a company, person, or model. Returns whether the entity is rising, stable, or declining in expert coverage; how much attention it's getting relative to others; whether the trend is statistically significant; and a notability assessment. Use this to understand an entity's trajectory before diving into specific signals.

**Parameters:**

| Param        | Type   | Required | Description                                |
| ------------ | ------ | -------- | ------------------------------------------ |
| `name_or_id` | string | Yes      | Entity name (fuzzy matched) or entity UUID |

**Example prompt:** *"Show me NVIDIA's entity profile"*

```json theme={null}
{ "name_or_id": "NVIDIA" }
```

<Note>Entities with fewer than 8 mentions in the 12-week window return `scale` only. The `direction`, `confidence`, `stability`, and `notability` fields will be `null` due to insufficient data for statistical significance.</Note>

### `get_themes`

List all taxonomy themes across two axes that categorize the AI economy. Each theme includes signal counts, trend direction, and notability. Use `get_theme_detail` for full trend analytics and co-occurring themes.

**Parameters:**

| Param  | Type   | Required | Description                     |
| ------ | ------ | -------- | ------------------------------- |
| `axis` | string | No       | `value_chain` or `market_force` |

**Taxonomy:**

* **Value chain:** Infrastructure, Foundation Models, Orchestration, Data & Labeling, Applications, Distribution
* **Market force:** Capital & Investment, Regulatory & Legal, Competitive Dynamics, Talent & Labor, Geopolitical Strategy, Trust & Societal Impact

**Example prompt:** *"What value chain themes are trending?"*

```json theme={null}
{ "axis": "value_chain" }
```

### `get_theme_detail`

Get a specific theme's full trend analytics and co-occurring themes from both axes. Returns trend direction, statistical confidence, stability, notability with reasoning, and which themes from the other axis most frequently co-occur. Use this to understand how themes interconnect.

**Parameters:**

| Param   | Type   | Required | Description                         |
| ------- | ------ | -------- | ----------------------------------- |
| `axis`  | string | Yes      | `value_chain` or `market_force`     |
| `label` | string | Yes      | Theme label (e.g. `Infrastructure`) |

**Example prompt:** *"Tell me about the Geopolitical Strategy theme"*

```json theme={null}
{ "axis": "market_force", "label": "Geopolitical Strategy" }
```

## Authentication & rate limits

The MCP server uses the same API key and rate limits as the REST API. Provide your key via the `x-api-key` header in your client's MCP config (see the examples above).

| Tier | Per-minute | Monthly                |
| ---- | ---------- | ---------------------- |
| Free | 20         | 250                    |
| Pro  | 60         | 5,000                  |
| Team | Custom     | Custom (contact sales) |

Rate limits are shared: requests from MCP and REST count toward the same quota. When you exceed the limit, the tool returns an error message with the retry-after interval.

## Troubleshooting

### "Authentication failed"

The API key is missing, invalid, or revoked.

1. Check that the `x-api-key` header is set in your MCP config
2. Verify the key starts with `gld_`
3. Check your key status at [gildea.ai](https://gildea.ai)

### "Rate limit exceeded"

You've hit the per-minute or monthly quota.

1. Check your current tier's limits in the table above
2. Wait for the retry-after interval (returned in the error message)
3. Consider upgrading your tier if you consistently hit limits

### Tools not appearing

1. Reload your client's MCP servers (or restart it) after editing the config
2. Verify the config is valid JSON (no trailing commas) and the `x-api-key` header is set
3. Confirm your key is active at [gildea.ai](https://gildea.ai)
4. Check the client's MCP logs for connection errors. For Claude Code, `claude mcp list` shows the connection status

### Connection issues

1. Confirm the URL is exactly `https://api.gildea.ai/mcp/`
2. Check the service is up: `curl https://api.gildea.ai/v1/health`
3. Check for network/firewall issues if your client can't reach it