MCP Server

Gildea provides an MCP (Model Context Protocol) server, giving AI assistants direct access to market intelligence data. Connect it to Claude Desktop, Cursor, or any MCP-compatible client.

Setup

Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gildea": {
      "command": "uvx",
      "args": ["--from", "gildea[mcp]", "gildea-mcp"],
      "env": {
        "GILDEA_API_KEY": "gld_your_key_here"
      }
    }
  }
}

Or run directly:

GILDEA_API_KEY=gld_your_key python -m gildea_sdk.mcp

Cursor

For Cursor or other HTTP-based MCP clients, run in SSE mode:

GILDEA_API_KEY=gld_your_key python -m gildea_sdk.mcp --sse --port 8001

Then point your client to http://localhost:8001/sse.

Self-hosted API

If you’re running the Gildea API on your own infrastructure, set the base URL:

{
  "mcpServers": {
    "gildea": {
      "command": "uvx",
      "args": ["--from", "gildea[mcp]", "gildea-mcp"],
      "env": {
        "GILDEA_API_KEY": "gld_your_key_here",
        "GILDEA_API_BASE_URL": "https://your-api-host.example.com"
      }
    }
  }
}

REST API vs MCP

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

	REST API	MCP Server
Best for	Apps, dashboards, pipelines	AI assistants (Claude, Cursor)
Protocol	HTTP/JSON	stdio or SSE
Auth	`X-API-Key` header	`GILDEA_API_KEY` env var
Rate limits	Shared quota	Shared quota
Pagination	Cursor-based	Limit param (no cursors)
Data	Identical	Identical

Rate limits are shared across REST and MCP. A request from Claude Desktop 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`

Semantic search across all of Gildea’s verified extractions — thesis sentences, arguments, summaries, and claims. Text units are Gildea’s own analytical extractions from source material, independently verified for factual accuracy. They are not direct quotes. Two modes: q for hybrid semantic + keyword search, or similar_to with a text unit ID for pure vector similarity (best for consensus mapping and cross-source synthesis). Exactly one is required. Parameters:

Param	Type	Required	Description
`q`	string	One of `q` / `similar_to`	Search query text
`similar_to`	string	One of `q` / `similar_to`	Text unit ID — finds similar units using stored embeddings
`unit_type`	string	No	Filter: `thesis_sentence`, `argument_sentence`, `summary_sentence`, `analysis_claim`, `event_claim`
`entity`	string	No	Filter by entity ID
`theme`	string	No	Filter by theme label
`limit`	integer	No	Max results (default: 10, max: 25)

Example prompt: “Search for verified claims about GPU supply constraints”

// Keyword search
{ "q": "GPU supply constraints", "unit_type": "analysis_claim", "limit": 5 }

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

// Similar-to search
{ "similar_to": "clm_01JABCDEF987654321", "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
`q`	string	No	Text search query
`content_type`	string	No	`analysis` or `event`
`published_after`	string	No	ISO date (e.g. `2026-02-01`)
`published_before`	string	No	ISO date
`limit`	integer	No	Max results (default: 25, max: 50)

Example prompt: “Show me recent analysis signals about OpenAI”

{ "entity": "org:/openai", "content_type": "analysis", "limit": 5 }

`get_signal_detail`

Get the full verified reasoning chain for a signal. This is where Gildea’s value lives. Analysis signals decompose into: thesis → supporting arguments → verified claims. Event signals decompose into: summary → verified claims. Each piece has been independently verified against source evidence. 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
`include`	string	No	Set to `evidence` for source snippets
`verification_detail`	string	No	Set to `full` for verification metadata

Example prompt: “Get the full decomposition of that signal with evidence”

{ "signal_id": "sig_01JEXAMPLE", "include": "evidence" }

`list_entities`

Discover which companies, people, and products are getting expert attention in the AI economy. Filter by trend direction, priority level, coverage scale, and more. Use this for discovery — finding what’s worth paying attention to. Parameters:

Param	Type	Required	Description
`q`	string	No	Fuzzy name search
`theme`	string	No	Filter by theme label
`type_primary`	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	`High`, `Medium`, `Low`
`priority`	string	No	`High`, `Medium`, `Low`, `Negligible`
`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 product. 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 priority 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 priority 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 priority. 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, priority 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" }

Sample conversation

Here’s what a real interaction looks like when Claude Desktop has the Gildea MCP server connected:

You: What are the most important things happening in AI right now?

Claude: Let me check the latest market intelligence. [Calls list_entities with direction=“Rising”, confidence=“Significant”, sort=“trend”] [Calls get_themes with axis=“value_chain”] Based on the latest signals from 500+ sources, here are the key dynamics: Rising entities:

OpenAI — High scale, Rising direction, Significant confidence. Priority: High.

Anthropic — Medium scale, Rising direction. Steadily gaining share.

Hottest themes:

Infrastructure — Rising with high confidence. The GPU/compute build-out narrative continues to intensify.

Regulatory & Legal — Significant upward trend driven by EU AI Act implementation.

You: Dig into what’s driving the Infrastructure theme.

Claude: [Calls get_theme_detail with axis=“value_chain”, label=“Infrastructure”] [Calls list_signals with theme=“Infrastructure”, limit=5] The Infrastructure theme has a Theil-Sen slope of 0.12 (Rising, Significant, Steady). Here are the latest signals driving it:

“TSMC Accelerates CoWoS Capacity Expansion” — Analysis signal with 8 verified text units…

“Microsoft Plans $80B Data Center Spend” — Event signal…

You: Search for anything about chip export controls.

Claude: [Calls search_text_units with q=“chip export controls”] Found 10 verified text units across 7 signals. The top results include thesis sentences about supply chain restructuring and claims about NVIDIA’s H20 shipments to China…

Authentication & rate limits

The MCP server uses the same API key and rate limits as the REST API. Set your key via the GILDEA_API_KEY environment variable.

Tier	Per-minute	Monthly
Free	5	200
Pro	30	2,000
Team	120	10,000

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 GILDEA_API_KEY is set in your MCP config
Verify the key starts with gld_
Check your key status on the dashboard

”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 in Claude Desktop

Restart Claude Desktop after editing the config file
Check the config path is correct: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS
Verify the JSON is valid (no trailing commas)
Check Claude Desktop logs for connection errors

SSE connection issues

Ensure the port isn’t already in use: lsof -i :8001
Check that the server is running: curl http://localhost:8001/sse should initiate a stream
For remote connections, ensure firewalls allow the port

API connectivity issues

The MCP server connects to the Gildea REST API over HTTPS.

Verify GILDEA_API_KEY is set correctly
If using GILDEA_API_BASE_URL, check the URL is reachable: curl https://your-api-host/v1/health
Check for network/firewall issues if you get connection errors

Getting Started

Core Concepts

Guides

Setup

Claude Desktop

Cursor

Self-hosted API

REST API vs MCP

Available tools

`search_text_units`

`list_signals`

`get_signal_detail`

`list_entities`

`get_entity_profile`

`get_themes`

`get_theme_detail`

Sample conversation

Authentication & rate limits

Troubleshooting

”Authentication failed”

”Rate limit exceeded”

Tools not appearing in Claude Desktop

SSE connection issues

API connectivity issues

Getting Started

Core Concepts

Guides

​Setup

​Claude Desktop

​Cursor

​Self-hosted API

​REST API vs MCP

​Available tools

​search_text_units

​list_signals

​get_signal_detail

​list_entities

​get_entity_profile

​get_themes

​get_theme_detail

​Sample conversation

​Authentication & rate limits

​Troubleshooting

​”Authentication failed”

​”Rate limit exceeded”

​Tools not appearing in Claude Desktop

​SSE connection issues

​API connectivity issues

Setup

Claude Desktop

Cursor

Self-hosted API

REST API vs MCP

Available tools

`search_text_units`

`list_signals`

`get_signal_detail`

`list_entities`

`get_entity_profile`

`get_themes`

`get_theme_detail`

Sample conversation

Authentication & rate limits

Troubleshooting

”Authentication failed”

”Rate limit exceeded”

Tools not appearing in Claude Desktop

SSE connection issues

API connectivity issues