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

# Armature MCP API for agent-driven testing

> Connect any MCP client to Armature to triage failing runs, propose workflow repairs, trigger validations, and inspect MCP coverage from one endpoint.

Armature exposes an agent-facing MCP endpoint at `/api/mcp`. Any MCP-compatible client—Claude Code, Claude Desktop, Cursor, Windsurf, or your own tooling—can connect to it using an Armature API key. Once connected, the agent has access to triage tools for investigating run failures, repair and proposal tools for patching workflows, run dispatch tools for triggering validations on demand, structured resources for traces and coverage reports, and guided prompts for common workflows. All tool responses include both a text JSON representation and a `structuredContent` block, so agents can work with results programmatically without additional parsing.

## Endpoint URL

Your Armature MCP endpoint is your organization's dashboard URL with `/api/mcp` appended:

```
https://your-org.armature.app/api/mcp
```

## Connecting an MCP client

To connect a client, add your Armature endpoint and API key to the client's MCP server configuration. The key goes in the `Authorization` header as a Bearer token—see [Authentication](/mcp-api/authentication) for how to generate one.

```json theme={null}
{
  "mcpServers": {
    "armature": {
      "url": "https://your-org.armature.app/api/mcp",
      "headers": {
        "Authorization": "Bearer amt_<key-id>_<secret>"
      }
    }
  }
}
```

Replace `your-org` with your Armature organization slug and `amt_<key-id>_<secret>` with a real API key. The key's role determines which tools and operations are available to the agent—see [Roles](/mcp-api/roles) for the full permission matrix.

## Optional `telemetry.intent` on every tool call

Every Armature MCP tool advertises an optional `telemetry` argument with a single string field, `intent`. Pass a one-sentence description of what the user is trying to accomplish with the call — same scope as the `report_intent` tool on the instrumented endpoint. Armature uses the intent to attribute tool calls to user goals on the Session Analytics dashboard. The field is stripped from the arguments before the tool handler runs, so it never reaches your workflow logic.

You do not have to pass `telemetry.intent` — calls without it succeed and still emit a tool-call event, just with the intent recorded as `null`. Attach the field when you want richer attribution on the dashboard.

```json theme={null}
{
  "name": "search_runs",
  "arguments": {
    "status": "fail",
    "limit": 20,
    "telemetry": {
      "intent": "Find the most recent failing checkout-flow runs to triage."
    }
  }
}
```

## What the endpoint exposes

The MCP endpoint is organized into five surfaces:

**Triage tools** let the agent search, inspect, and diagnose workflow runs, and retrieve overall organization health. These are read-only and safe to call at any time.

**Repair and proposal tools** let the agent stage a patch against a workflow, draft a regression workflow from a failed run, and apply an approved change. Applying a change requires editor role or higher.

**Run tools** let the agent dispatch a manual workflow run with an optional wait for completion, and compare two runs to surface regressions.

**Resources** expose structured data—run traces, run artifacts, workflow schemas, the model catalog, evaluation criteria documentation, MCP server tool catalogs, coverage reports, and staged change proposals—as addressable `armature://` URIs.

**Prompts** provide guided multi-step sequences for the most common agent tasks: repairing a failing workflow and designing a workflow test suite.

## Available surfaces at a glance

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/mcp-api/authentication">
    Generate API keys, set the Authorization header, and understand token security requirements.
  </Card>

  <Card title="Roles" icon="shield" href="/mcp-api/roles">
    Understand which tools and operations each role can access through the MCP endpoint.
  </Card>

  <Card title="Triage tools" icon="magnifying-glass" href="/mcp-api/tools/triage">
    Search runs, inspect run details, diagnose failures, and check organization health.
  </Card>

  <Card title="Repair tools" icon="wrench" href="/mcp-api/tools/repair">
    Propose workflow patches, draft regression workflows, and apply approved changes.
  </Card>

  <Card title="Resources" icon="database" href="/mcp-api/resources">
    Access run traces, coverage reports, workflow schemas, and staged proposals by URI.
  </Card>

  <Card title="Prompts" icon="message" href="/mcp-api/prompts">
    Use guided multi-step prompts to repair failing workflows and design test suites.
  </Card>
</CardGroup>