# MCP server

`synthient mcp` runs a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, exposing lookups, feed metadata, and schemas as tools for any MCP-compatible client.

It ships inside the [CLI](https://docs.synthient.com/cli), so there is nothing separate to install:

```bash
brew install synthient/tap/synthient
synthient mcp
```

The server authenticates with the [usual credential order](https://docs.synthient.com/cli#authentication): `SYNTHIENT_API_KEY`, a `.env` in the working directory, then the OS keychain. It exits at startup if no key is found. The only flag is `--transport`, which currently accepts `stdio`.

## Tools

| Tool                  | Purpose                                                       |
| --------------------- | ------------------------------------------------------------- |
| `lookup_ip`           | Look up intelligence for one or more IP addresses             |
| `lookup_domain`       | Look up domain intelligence from Helios observations          |
| `get_account`         | Report organization, scopes, and lookup quota                 |
| `list_feed_streams`   | List available feed streams with descriptions and aliases     |
| `list_feed_snapshots` | List Parquet snapshots for a stream, with pagination          |
| `feed_snapshot_meta`  | Snapshot metadata, checksum, size, row count, and schema      |
| `sample_stream`       | Collect a bounded sample of live events from a real-time feed |
| `grpc_schema`         | Fetch protobuf descriptors through gRPC reflection            |

Prefer these over hand-rolled HTTP when the runtime supports MCP: they handle authentication, pagination, and stream bounding for you. `lookup_ip` takes many addresses at once, which costs `ceil(n * 0.9)` credits instead of `n`.

## Registering the server

The [Claude Code](https://docs.synthient.com/ai/claude) and [Codex](https://docs.synthient.com/ai/codex) plugins register the server for you. Everywhere else, meaning Claude Desktop, an editor, or your own agent runtime, declare it yourself, using an absolute path to the binary if `synthient` isn't on the launcher's `PATH`:

```json
{
  "mcpServers": {
    "synthient": {
      "command": "synthient",
      "args": ["mcp"]
    }
  }
}
```

> **Note**: A launcher started from the desktop rather than a shell often has neither your `PATH` nor your environment. If the server exits immediately, that is usually a missing binary path or a key the process never saw. The keychain, populated once with `synthient auth`, is the credential source that survives it.

## What stays in the CLI

The tools cover the read surfaces an agent asks for mid-conversation. Bulk and long-running work stays in the [CLI](https://docs.synthient.com/cli): snapshot downloads with checksum verification, filtered or long-running stream capture, CSV export, and the `status` / `scopes` diagnostics. The plugin skills drive those directly when a task needs them.

An agent with no tool access at all still has a machine-readable path: every page here is published as plain markdown at its own `.md` URL, and the whole product is condensed into the two [llms.txt](https://docs.synthient.com/#built-for-llms-and-agents) files.