# NewsDesk MCP Server

Connect AI agents to NewsDesk's live structured news intelligence database via the [Model Context Protocol](https://modelcontextprotocol.io/).

**This is a hosted MCP server.** No installation required — connect any MCP-compatible client to `https://app.newsdesk.dev/mcp` and authenticate with Google.

## What is NewsDesk?

NewsDesk converts raw news articles into a structured database of **events**, **entities** (people, companies, countries — 17 types), **relationships**, and **actions**. The MCP server gives AI agents direct access to query this data using natural language.

## Quick Start (2 minutes)

### 1. Create `.mcp.json`

Add this file to the directory where you run your MCP client:

```json
{
  "mcpServers": {
    "newsdesk": {
      "type": "http",
      "url": "https://app.newsdesk.dev/mcp"
    }
  }
}
```

No API keys or tokens to manage.

### 2. Restart your client

Claude Code, Cursor, Windsurf, and other MCP clients pick up `.mcp.json` on startup.

### 3. Sign in

On first connection, your client opens a browser for Google sign-in. Use the same account you use for the [NewsDesk dashboard](https://newsdesk.dev). Your session is cached after the first sign-in.

### 4. Start querying

Ask your agent questions like:

- "What's happening with NVIDIA and China?"
- "How are Elon Musk and the SEC connected?"
- "Find all government agencies that took negative actions against tech companies"
- "Find the path between Donald Trump and Saudi Arabia"

The agent automatically selects the right tools to answer.

## Tools (17)

| Category | Tools | What they do |
|----------|-------|-------------|
| **Discovery** | `get_schema`, `get_stats` | Data model reference, database statistics |
| **Entity** | `search_entities`, `get_entity`, `get_entity_events` | Find and inspect any of 17 entity types |
| **Event** | `get_event`, `get_events_batch`, `search_events`, `similar_events` | Semantic search, structured filters, similarity, bulk fetch |
| **Relationship** | `get_entity_relationships`, `get_relationship`, `entity_co_mentions` | Browse connections, pair details, co-mention strength |
| **Action** | `get_entity_actions`, `get_actions_between`, `search_actions` | Who did what to whom — sanctions, acquisitions, agreements |
| **Graph** | `graph_query`, `find_paths` | Multi-hop pattern matching, shortest paths between entities |

See [TOOLS.md](TOOLS.md) for full parameter documentation and examples.

## Entity Types

| Code | Type | Example |
|------|------|---------|
| `per` | Person | `per___Donald_Trump` |
| `stock` | Public company | `stock___NVIDIA` |
| `priv` | Private company | `priv___SpaceX` |
| `subs` | Subsidiary | `subs___YouTube` |
| `cnt` | Country | `cnt___China` |
| `govactor` | Government agency | `govactor___United_States===Federal_Reserve` |
| `cbnk` | Central bank | `cbnk___Japan===Bank_of_Japan` |
| `polparty` | Political party | `polparty___United_States===Republican_Party` |
| `curr` | Currency | `curr___US_Dollar` |
| `cmdt` | Commodity | `cmdt___Crude_Oil` |
| `crypto` | Cryptocurrency | `crypto___Bitcoin` |
| `index` | Market index | `index___S&P_500` |
| `exch` | Stock exchange | `exch___NYSE` |
| `alliance` | International alliance | `alliance___NATO` |
| `ngo` | NGO | `ngo___Amnesty_International` |
| `mil` | Military | `mil___United_States===US_Army` |
| `loc` | Location | `loc___Silicon_Valley` |

Entity reference format: `type___Name` (triple underscore). Parent-child: `type___Parent===Child`.

## Example Workflows

**Entity lookup**
> "Tell me about Tesla"

Agent calls: `search_entities("Tesla")` → `get_entity("stock___Tesla_Inc.")` → `get_entity_events("stock___Tesla_Inc.")`

**Relationship exploration**
> "How are the US and China connected?"

Agent calls: `search_entities("United States")` → `get_entity_relationships("cnt___United_States")` → `get_relationship("cnt___United_States", "cnt___China")`

**Semantic search**
> "What events are related to AI regulation in Europe?"

Agent calls: `search_events(query="AI regulation Europe")`

**Complex graph pattern**
> "Find all CEOs of companies that have relationships with China"

Agent calls: `graph_query({nodes: {CHINA: anchor, COMPANIES: intermediate, CEOS: result}, edges: [...]})`

**Pathfinding**
> "How is Elon Musk connected to the Federal Reserve?"

Agent calls: `find_paths("per___Elon_Musk", "govactor___United_States===Federal_Reserve")`

## Supported Clients

- [Claude Code](https://claude.ai/code) (CLI, desktop, web, IDE extensions)
- [Cursor](https://cursor.sh)
- [Windsurf](https://codeium.com/windsurf)
- Any client supporting the [MCP specification](https://modelcontextprotocol.io/)

## Authentication

OAuth 2.0 via Google. The MCP client handles the flow automatically — a browser window opens on first connection, and the session is cached afterward. No API keys to manage.

Requires a NewsDesk account. [Request access](mailto:access@newsdesk.io) if you don't have one.

## Links

- [Full tutorial](https://newsdesk.dev/mcp-tutorial.html)
- [NewsDesk Dashboard](https://newsdesk.dev)
- [API Documentation](https://newsdesk.dev/api.html)
- [Pricing](https://newsdesk.dev/pricing.html)

## License

MIT — see [LICENSE](LICENSE).