PublishedDocs / Augments

MCP

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

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

toolslifecycleadmin 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

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

agent.yamlyaml

augments:
  - mcp

.mcp.jsonjson

{
  "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

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 requesttext

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

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

Add an augmentInstall layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.MCPBridge local or remote MCP server tools into Auggy with deploy-aware policy.Deploy and verifyDeploy the agent to Railway and verify its health, route, console, and application client.SecurityAuggy's security boundaries, the prompt-injection threat model, and how to report a vulnerability privately.

MCP