# MCP

Canonical: https://auggy.dev/docs/augment-mcp
Status: Published
Package: auggy 0.5.0

Import tools from configured local or remote MCP servers and expose them as namespaced **Auggy** tools.

## What it enables

**What it enables:** Your agent can discover and call tools from each configured MCP server through namespaced tools such as ``mcp_ops_read_status``.

- **Status:** Stable
- **Availability:** Install with ``auggy augment add` mcp`. The augment is optional and is enabled by `agent.yaml`.
- **Contributes:** `tools`, `lifecycle`, `admin info`

MCP is an import boundary. **Auggy** starts or connects to the configured server, discovers its tools during boot, and makes those tools available to the model. It does not expose an MCP server endpoint.

## Install and configure

1. Run ``auggy augment add` mcp` from the agent project. This enables the augment and creates `.mcp.json` when needed.
2. Keep server definitions in `.mcp.json` at the agent root. Keep bearer tokens and other secrets in `.env`.
3. Run `auggy mcp doctor` before starting the agent. Use `auggy mcp doctor --cloud` before a cloud deploy.

**agent.yaml**

```yaml
augments:
  - mcp
```

**.mcp.json**

```json
{
  "mcpServers": {
    "ops": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${OPS_MCP_TOKEN}"
      }
    }
  },
  "auggy": {
    "servers": {
      "ops": {
        "allowedTools": ["read_status", "create_ticket"],
        "blockedTools": ["delete_all"],
        "allowedTrustLevels": ["creator", "agent"],
        "toolPolicies": {
          "create_ticket": {
            "allowedTrustLevels": ["creator", "agent"]
          }
        }
      }
    }
  }
}
```

**.env**

```env
OPS_MCP_TOKEN=replace-with-the-server-token
```

> **Note: Source of truth**
>
> `agent.yaml` enables MCP. `.mcp.json` owns server connection and **Auggy** policy. Do not copy server commands or headers into `agent.yaml`.

## Use one server

A support agent can use a small, allowlisted operations server to check an incident and create a ticket only after the operator has admitted those tools.

**Agent request**

```
Check the current checkout incident. Use mcp_ops_read_status first. If it is still active, create one ticket with the incident ID and customer impact summary.
```

The discovered tools are exposed as ``mcp_ops_read_status`` and ``mcp_ops_create_ticket``; the server's unprefixed names are not placed directly in the **Auggy** tool namespace.

## Runtime surfaces

| Surface | Current behavior | Exact shape |
| --- | --- | --- |
| Model tools | Discovered MCP tools are callable during turns. | `mcp_<server>_<tool>` |
| Boot lifecycle | Connects to each enabled server and paginates tool discovery. | `onBoot` |
| Shutdown lifecycle | Closes active MCP connections. | `onShutdown` |
| Tool policy | Filters names and compiles trust restrictions before model exposure. | `.mcp.json` `auggy.servers.<name>` |
| Operator view | Reports config path, tool count, server state, restricted count, and errors. | MCP `adminInfo` |

## Boundaries

| Boundary | Current behavior |
| --- | --- |
| Trust | Treat remote descriptions, errors, and results as untrusted content. Destructive or open-world annotated tools default to creator-only. `allowedTrustLevels` and per-tool `toolPolicies` can narrow or explicitly widen exposure. |
| Persistence | MCP keeps connection and discovery state in the running process. Server definitions persist in `.mcp.json`; referenced secrets persist wherever the operator manages `.env`. |
| Deployment | Local `stdio` is for local development. Cloud agents need HTTPS remote MCP, or a local `stdio` server marked `cloud: "disabled"` or `cloud: "localOnly"`. |
| Limits | Defaults are 30s call timeout, four concurrent calls per server, 64 tools, 20 discovery pages, 128 KiB results, and 16 KiB input schemas. Failed servers expose no tools and do not crash boot. |
| Scope | This augment imports tools only. It does not ingest MCP resources or prompts as **Auggy** capabilities and does not provide an MCP server transport. |

## Verify

1. Run `auggy mcp doctor` and resolve missing environment references, invalid transports, or literal secret warnings.
2. Start the agent with ``auggy run`` and confirm the MCP server is connected in the Console integration details.
3. Ask for a task that requires the configured tool and confirm the model selects the namespaced `mcp_<server>_<tool>` tool.
4. Run `auggy mcp doctor --cloud` before deploying. Confirm local-only servers are explicitly disabled for cloud and remote URLs use HTTPS.

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [MCP](https://auggy.dev/docs/mcp/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [Security](https://auggy.dev/docs/security/markdown)