MCP Server

Let AI assistants such as Claude run Functions, read data, and call API endpoints as MCP Tools.
Framework Docs Menu

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.

AI client (ex. Claude) claude mcp add --transport http trakhound http://host:8472/_mcp --header "X-API-Key: thk_..."
Access checkread on system:mcp to connect and use read-only Tools; write for Tools that change something; plus each Tool's own resource
Rate Limits can cap Tool calls per client
The client only sees what the caller may use
Built-in ToolsRun Functions, read Logs, query Tables, read and set Key-Values, publish Messages, read Volume files, describe APIs
Your API endpointsMarked with [ApiMcpTool]; read-only by default (mcpTools, mcpReadOnly)
Resourcestrakhound://llms.txt and each API's OpenAPI document
Promptsinstance_overview, diagnose_function, explore_api, query_tables
Off by default. Turn it on in Settings > Interfaces, and add a security profile before connecting from other machines.

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 is on. Add a profile before connecting clients from other machines.

Access

ResourcePermissionAllows
system:mcpreadConnecting, and the Tools that only read
system:mcpwriteAlso 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.

API Endpoints as Tools

Choose which endpoints of each API are Tools in its configuration (Config > Api > MCP Tools):

SettingDescription
mcpToolsOff, 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).
mcpReadOnlyRead-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, mcpExcludePatterns, 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)
{
    ...
}
PropertyDescription
NameThe Tool name, prefixed with the API's route.
DescriptionWhat the Tool does and when to use it, written for an AI agent.
ReadOnlyThe endpoint only reads. GET and stream endpoints are read only by default; set this on another method that only reads (ex. a POST search).
DestructiveThe 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:

KindNameDescription
Resourcetrakhound://llms.txtThe Instance's llms.txt: how to connect, and each API the caller can use.
Resourcetrakhound://apis/{apiId}/openapiEach API's OpenAPI document, with only the endpoints the caller can call.
Promptinstance_overviewSummarizes what the Instance runs and whether anything needs attention.
Promptdiagnose_functionFinds out why a Function is failing or slow, from its details, runs, and logs.
Promptexplore_apiExplains what an API does and how to call it.
Promptquery_tablesAnswers 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. Tool calls over the limit return a Tool error that says when to retry.