# MCP Server

> Let AI assistants such as Claude run Functions, read data, and call API endpoints as MCP Tools.

URL: https://www.trakhound.com/docs/trakhound-framework/mcp-server

Every Instance can serve an MCP (Model Context Protocol) Server at `/_mcp`, so AI assistants such as Claude can use the Instance: list and run Functions, read Logs, query Tables, read and set Key-Values, read and write Time Series, publish and wait for Messages, read Volume files, and describe the APIs. API endpoints can be offered as Tools too. Access is controlled by the same security profiles and API keys as the rest of the Instance.

Diagram: An AI client such as Claude connects to the Instance's MCP Server at /\_mcp with an API key. Access is checked against security profiles: read on system:mcp for read-only Tools, write for Tools that change something. The client sees built-in Tools for Functions, Logs, Tables, Key-Values, Messages, Volumes and APIs, Tools from API endpoints marked ApiMcpTool, Resources such as llms.txt and OpenAPI documents, and Prompts.

## Turn It On

1. In the admin UI, open **Config > Settings > Interfaces** and turn on **MCP Server** (the System API must be on too), or set `mcpEnabled: true` in `instance.config.yaml`. It applies when saved.
2. Create an API key under **Security > API Keys** with roles that are granted the access below.
3. Connect a client to `http://{host}:{port}/_mcp`. The MCP Server is served on the HTTP port, and on the Admin port when there is one. For example, with Claude Code:

```
claude mcp add --transport http trakhound http://localhost:8472/_mcp --header "X-API-Key: thk_..."
```

> The MCP Server is off by default. Access works like the rest of the System API: security profiles decide who can use it. **Without a profile, every Tool, including running Functions and SQL, can be used by anyone on the Instance's own machine**, and by anyone who can reach the Instance when [Unprotected Remote Access](https://www.trakhound.com/docs/trakhound-framework/security#unprotected) is on. Add a profile before connecting clients from other machines.

## Access

| Resource | Permission | Allows |
| --- | --- | --- |
| `system:mcp` | `read` | Connecting, and the Tools that only read |
| `system:mcp` | `write` | Also the Tools that change something: `functions_run`, `functions_cancel`, `tables_query` (runs any SQL), `keyvalues_set`, `timeseries_write`, and `messages_publish` |

Each Tool also needs the permission for what it uses, for example `system:functions` (`write` to run), `system:logs`, `system:volumes`, or `system:api-information`. Key-Value, Table, and Message Tools are authorized by the Service, the same as other Service calls. Clients are only shown the Tools the caller can use. See [Security](https://www.trakhound.com/docs/trakhound-framework/security).

## API Endpoints as Tools

Choose which endpoints of each API are Tools in its configuration (**Config > Api > MCP Tools**):

| Setting | Description |
| --- | --- |
| `mcpTools` | `Off`, `Marked` (default: endpoints the Package author marked with `[ApiMcpTool]`), or `All` (every endpoint; unmarked ones are named after their method and described by their route). |
| `mcpReadOnly` | **Read-only Tools only**. On by default, so only Tools that don't change anything are served: GET and stream endpoints, plus endpoints marked read only. Turn it off to also serve endpoints that change data. |
| `mcpInclude`, `mcpExclude` | Patterns, one per line, that narrow the Tools further. A pattern is a route relative to the API's route with `*` matching anything, optionally after a method list: `GET *`, `GET,HEAD /parts/*`, `STREAM *`, or `DELETE *`. |

Tool names start with the API's route (ex. `api_orders_get_order`). Calling one is authorized like an HTTP request to the endpoint, and endpoints that change something also need `write` on `system:mcp`. Use the patterns with `All` on large APIs: AI clients choose tools less reliably when there are many.

### Marking Endpoints in Your Package

Mark endpoints that are safe for an AI agent to call with `[ApiMcpTool]`, and describe their inputs:

```
[ApiGet("orders/{id}")]
[ApiMcpTool(Name = "get_order", Description = "Returns an order with its status and due date. Use it to answer questions about a specific order.")]
public async Task<TrakHoundApiResponse> GetOrder([FromRoute(Description = "The order number, ex. 10452")] string id)
{
    ...
}

[ApiPost("orders/search")]
[ApiMcpTool(ReadOnly = true, Description = "Searches orders by customer and date range")]
public async Task<TrakHoundApiResponse> Search([FromBody(ContentType = "application/json")] OrderSearch search)
{
    ...
}
```

| Property | Description |
| --- | --- |
| `Name` | The Tool name, prefixed with the API's route. |
| `Description` | What the Tool does and when to use it, written for an AI agent. |
| `ReadOnly` | The endpoint only reads. GET and stream endpoints are read only by default; set this on another method that only reads (ex. a POST search). |
| `Destructive` | The endpoint deletes or overwrites data, or affects equipment, so clients ask before calling it. |

The Tool's inputs come from the endpoint's route, query, and body parameters, using their `Description`. Stream endpoints become Tools that collect values for a number of seconds. Tools follow the loaded APIs, so clients see changes the next time they list the Tools.

## Resources and Prompts

Besides Tools, the MCP Server offers:

| Kind | Name | Description |
| --- | --- | --- |
| Resource | `trakhound://llms.txt` | The Instance's [llms.txt](https://www.trakhound.com/docs/trakhound-framework/api-catalog#llms-txt): how to connect, and each API the caller can use. |
| Resource | `trakhound://apis/{apiId}/openapi` | Each API's OpenAPI document, with only the endpoints the caller can call. |
| Prompt | `instance_overview` | Summarizes what the Instance runs and whether anything needs attention. |
| Prompt | `diagnose_function` | Finds out why a Function is failing or slow, from its details, runs, and logs. |
| Prompt | `explore_api` | Explains what an API does and how to call it. |
| Prompt | `query_tables` | Answers a question by finding the right Tables and reading them with SELECT queries. |

Resources need `read` on `system:api-catalog`, like the API Catalog.

## Monitoring and Rate Limits

**Explorer > Diagnostics > Metrics > MCP** shows Tool calls, errors, denied calls, durations, and the clients that connected. To stop an AI client that loops or retries quickly from slowing down the Instance, turn on [Rate Limits](https://www.trakhound.com/docs/trakhound-framework/security#rate-limits). Tool calls over the limit return a Tool error that says when to retry.
