MCP integration

MCP (Model Context Protocol) lets an AI desktop app, editor, or agent call selected tapstate control-plane operations through a standard tool interface. Tapstate provides a local MCP gateway in the complete CLI bundle.

The gateway is an optional integration for a self-hosted server. It does not install or start a tapstate server, provide a web UI, or expose an MCP HTTP endpoint from the server. Cloud uses managed browser sign-in; the machine-token setup below applies to self-hosted deployments.

How the connection works

The MCP host starts tapstate mcp as a local process and speaks MCP over the process's standard input and output. The gateway then calls an already-running tapstate server over its authenticated HTTP(S) control plane.

This means the CLI and the server have separate responsibilities:

• The MCP host launches and supervises the local gateway.
• The CLI bundle supplies the tapstate mcp command and its sidecar.
• The tapstate server authenticates requests and performs the operation.
• The MCP gateway does not replace the server or the server's authorization checks.

The current server-backed path is provided by the disposable Docker Quickstart. This release does not include a standalone server installer. Run the Quickstart when you need a local server to test the integration.

Requirements

Before configuring an MCP host, make sure that:

1. You installed the complete CLI bundle, not only a standalone bin/tapstate binary. The bundle keeps bin and libexec together so the CLI can find its sidecar.
2. A tapstate server is already running and reachable from the gateway.
3. You have administrator credentials to create a scoped machine token, or an existing machine token with the scope required by the tools you plan to use.
4. The complete CLI bundle's sidecar is tapstate-mcp.jar, so Java 21 or newer is required for this release. The native CLI's offline commands do not require Java.

For a loopback server, use http://127.0.0.1:8080 or another loopback address. For a remote server, use HTTPS. The gateway rejects a non-loopback HTTP URL.

Authenticate the host

Do not give an MCP host the tapstate administrator password. Use the password once in an interactive CLI session, then create a scoped machine token for the host.

Start the CLI and connect to the server:

tapstate -w tapstate-work

In the CLI, log in as an administrator and enter the password only when the prompt requests it:

connect http://127.0.0.1:8080
login admin
Password:

Create a read token for read-only tools:

token create --scope read -o json

Use a dedicated read token for each MCP host. The bearer value is displayed once; copy it into the host's protected local secret configuration. The host presents this token to the tapstate server on every request, and the server verifies its scope. The host does not repeat the administrator-password login.

When an MCP tool accepts connector settings, you can use environment references in those settings. ${VAR} requires VAR to be set; ${var:NAME:default} uses default when NAME is not set. The local gateway expands these references before it sends the request. A missing required variable returns mcp.environment-missing; keep the values in the host or process environment instead of putting secrets in tool arguments.

See Manage machine tokens for list and revoke commands, or the REST API machine-token endpoints for the HTTP request and response.

Start the gateway manually

Set TAPSTATE_TOKEN in the environment through your shell's secret-handling method rather than passing the value as a command argument. The gateway accepts TAPSTATE_SERVER_URL as a default server URL; passing --server makes the target explicit:

tapstate mcp --server http://127.0.0.1:8080

When the command starts successfully, it waits for MCP JSON-RPC messages on standard input. It is not an interactive tapstate prompt. Keep this process in the foreground when testing it manually; an MCP host normally starts and stops it for you.

If the server is remote, use its HTTPS URL:

tapstate mcp --server https://tapstate.example.com

Do not put a real token in a checked-in host configuration, shell history, or a support report. Use the host's secret or environment-variable facility.

Configure an MCP host

MCP hosts use different settings locations, but the registration has the same shape: launch the installed tapstate executable, pass mcp and the server URL as arguments, and provide TAPSTATE_TOKEN as an environment variable.

Set TAPSTATE_TOKEN in the current shell using your local secret-handling method. The following commands copy its current value into the client's local MCP configuration.

codex mcp add \
  --env TAPSTATE_TOKEN="$TAPSTATE_TOKEN" \
  tapstate -- \
  "$HOME/.tapstate/bin/tapstate" mcp \
  --server http://127.0.0.1:8080

codex mcp get tapstate

claude mcp add --scope user tapstate \
  -e TAPSTATE_TOKEN="$TAPSTATE_TOKEN" -- \
  "$HOME/.tapstate/bin/tapstate" mcp \
  --server http://127.0.0.1:8080

claude mcp get tapstate

Protect the resulting client configuration as a secret-bearing file. Do not commit it to a repository or include it in a support report.

Other MCP hosts

For a host that accepts an mcpServers JSON object, the shape is:

{
  "mcpServers": {
    "tapstate": {
      "command": "/Users/you/.tapstate/bin/tapstate",
      "args": [
        "mcp",
        "--server",
        "http://127.0.0.1:8080"
      ],
      "env": {
        "TAPSTATE_TOKEN": "<server-token>"
      }
    }
  }
}

Replace command with the absolute path to the installed CLI on your system. If you installed to another directory, use that directory's tapstate entry point. Keep the corresponding libexec/tapstate-mcp.jar beside the versioned CLI bundle; moving only the executable breaks sidecar discovery.

After saving the host configuration, restart or reload the host according to its instructions. A healthy integration should start the process, complete the MCP initialization handshake, and return the read-only tools from tools/list.

Verify the connection

After reloading the host:

1. Confirm that the tapstate MCP entry starts without a handshake or authentication error.
2. Confirm that the client's available MCP tools include system_version and connector_list.
3. Ask the host to call system_version. It identifies the server before the agent reasons about supported operations.
4. Ask the host to call connector_list. A successful call verifies the local process, MCP handshake, server URL, and machine token.

If a tool call returns isError: true, the MCP layer is reporting a failed tool call. The failure can come from the local gateway, an unreachable server, or a server-side refusal; a successful handshake or tools/list call does not prove that every operation will succeed. Inspect the returned code, message, and params, then check the server URL, token scope, and server state.

Tools

Read-only tools

By default, the gateway exposes read-only tools:

pipeline_list does not include draft-only pipelines. The gateway does not expose the Web draft workflow or streaming Data Preview in v0.7.

For Sources, artifact_get omits connector config from the display YAML. Its content hash still identifies the full stored resource; do not use the display representation as a backup or reapply it as a complete definition.

pipeline_status separates desiredState, displayState, and runtime observation. A known pipeline without an observation returns state: "NEW" without observedState or observedAt. Metrics, snapshot, and explain can still return monitor.no-observation.

Write tools

Start the gateway with --allow-write and a write-scoped token to expose these additional tools. Enabling tools does not bypass server authorization.

Connection test and discovery wait for the connector without a fixed request deadline. If a call is interrupted, inspect the stored test result or schema before retrying. Read the tool's returned outcome and coded errors; a successful protocol exchange alone does not establish a passed test.

Pipeline history and explanations

pipeline_metrics_history requires id, from, and to. Use RFC3339 timestamps with UTC offsets and a range of at most 15 days. Optional parameters are resolution, limit, table, and cursor:

{
  "id": "orders",
  "from": "2026-09-29T01:00:00Z",
  "to": "2026-09-29T02:00:00Z",
  "resolution": "PT5M",
  "table": ["orders", "shipments"],
  "limit": 240
}

Use table, not tables. Resolutions are auto, raw, PT5M, PT30M, PT1H, PT3H, and PT6H. The maximum limit is 1000 and at most 20 tables can be selected. Omitting table omits table lag.

Repeat the same query with nextCursor as cursor to continue. A cursor expires after 10 minutes. Preserve resets, gaps, unavailable metrics, and NO_RETAINED_SAMPLES when explaining results; none means zero throughput. See History semantics.

pipeline_explain accepts id and interprets existing observation evidence. NO_MATCH does not prove healthy delivery. A missing observation returns monitor.no-observation; it is not a request to start the pipeline.

Browse data

The data-browser tools read through a declared source's configured connection. They do not accept a database URI or a database query language. The source and collection name are required; data_browser_find also accepts optional filter, sort, and limit values:

Data access boundary: Data-browser tools are read-only, but they can return source records to the MCP host. In this preview, data-browser access does not have a separate permission and these reads do not create audit events. Give the host a dedicated read-scoped token, restrict who can control the host, and avoid sensitive sources while evaluating the integration.

{
  "sourceId": "warehouse",
  "collection": "orders",
  "filter": {
    "field": "status",
    "op": "eq",
    "value": "paid"
  },
  "sort": {
    "field": "total",
    "dir": "desc"
  },
  "limit": 25
}

The filter vocabulary is eq, ne, gt, gte, lt, lte, in, exists, and contains. You can combine terms with one level of all or any. A literal dotted field name is written as price\\.usd in JSON. The API rejects database-native operators and arbitrary nested Boolean groups.

data_browser_find is a one-shot preview: the default is 10 rows, the maximum is 200 rows, and no cursor or next-page token is available. In this preview, row previews are available only for sources that use the mongodb connector. Collection listing and statistics can still be available for other connectors.

The gateway does not expose the CLI's live watch or tail views. Use the CLI reference when a person needs to follow changes in a terminal.

The host's tools/list response is the runtime authority if a later release adds, removes, or renames a tool.

Troubleshooting

The gateway writes protocol frames to stdout. Do not wrap it in a command that prints banners or diagnostics to stdout; non-protocol output can prevent the host from completing the MCP handshake.

Related pages

• Install the CLI
• CLI reference
• REST API preview
• Quickstart