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

# MCP server

> Connect the Bonai News API to AI tools with the Model Context Protocol

The Bonai News API ships with a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. You can connect it to AI assistants like Claude Desktop, Cursor, or opencode to search news, fetch articles, and discover trending topics directly from your assistant.

## Requirements

MCP access must be enabled on your plan. Requests to `/mcp` that don't have the entitlement return `403`.

## Endpoint

The server uses streamable HTTP in JSON mode:

```
https://api.bonai.io/news/mcp
```

* `POST /mcp`: JSON-RPC messages, including `initialize`, `tools/list`, and `tools/call`.
* `GET /mcp`: opens the optional server-sent events stream. The server runs stateless, so clients can use `POST` alone.

Authenticate with the same API key you use for the REST API, as a bearer token (`Authorization: Bearer`) or in the `api-key` / `x-api-key` header. You can also send `api-version` to pin a specific API version.

```bash theme={null}
curl --request GET \
  --url "https://api.bonai.io/news/mcp" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## Tools

The server exposes seven tools:

| Tool | Description |
| - | - |
| `search_articles` | Full-text search across news articles with optional filters. |
| `get_article` | Fetch a single article with full content by `url` or `id`. |
| `get_trending_articles` | Get trending articles for a topic and language. |
| `search_publishers` | Search news publishers by name or category. |
| `list_topics` | List all supported news topics and subtopics. |
| `list_languages` | List all supported languages. |
| `list_countries` | List all supported countries and their languages. |

## Configure a client

Point your client at the endpoint with your API key as a header. For example, in Claude Desktop's `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "bonai-news-api": {
      "type": "http",
      "url": "https://api.bonai.io/news/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

In opencode's `opencode.json`:

```json theme={null}
{
  "mcp": {
    "bonai-news-api": {
      "type": "remote",
      "url": "https://api.bonai.io/news/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

## Billing

Each `tools/call` message consumes one quota unit from your plan. The session handshake and `tools/list` calls are free.

<Warning>
  Keep your API key out of shared configuration files and source control. Use environment variables or a secret manager in production.
</Warning>