MCP Server - Gildea API

Gildea provides an MCP (Model Context Protocol) 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

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):

{
  "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:

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

See the MCP client list 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”

// Keyword search
{ "q": "GPU supply constraints", "role": "claim", "limit": 5 }

Example prompt: “Find text units similar to this claim”

// 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”

{ "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”

{ "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”

{ "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”

{ "name_or_id": "NVIDIA" }

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.

`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?”

{ "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”

{ "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.

Check that the x-api-key header is set in your MCP config
Verify the key starts with gld_
Check your key status at gildea.ai

”Rate limit exceeded”

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

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

Tools not appearing

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

Connection issues

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

​Claude Code

​Cursor

​Other MCP clients

​Claude Desktop

​REST API vs MCP

​Available tools

​search_text_units

​list_signals

​get_signal_detail

​list_entities

​get_entity_profile

​get_themes

​get_theme_detail

​Authentication & rate limits

​Troubleshooting

​”Authentication failed”

​”Rate limit exceeded”

​Tools not appearing

​Connection issues

Claude Code

Cursor

Other MCP clients

Claude Desktop

REST API vs MCP

Available tools

`search_text_units`

`list_signals`

`get_signal_detail`

`list_entities`

`get_entity_profile`

`get_themes`

`get_theme_detail`

Authentication & rate limits

Troubleshooting

”Authentication failed”

”Rate limit exceeded”

Tools not appearing

Connection issues