MCP Servers

Overview

MCP (Model Context Protocol) is an open standard for tool servers. An MCP server exposes a list of tools over HTTP and the agent can call them at runtime, without you defining a custom tool for each one.

ArchAgents lets you add an MCP server to an agent the same way you add any other tool. You declare the server in YAML, the platform handles authentication and tool discovery, and the agent gets access to everything the server exposes.

Use MCP when:

• you want to use tools from a third-party service that already speaks MCP (Stripe, Linear, Sentry, Notion, and many others)
• you have an internal tool server speaking MCP and want to expose it to agents
• you want one connection to provide many related tools instead of defining each tool by hand

---

How it works

1. You add an MCPServer entry to the agent's tools list in YAML.
2. The platform connects to the server's URL and discovers the tools it exposes.
3. Each discovered tool becomes available to the agent's LLM.
4. When the agent invokes a tool, the platform calls the MCP server with the right credentials and returns the result.

You don't write a tool definition for each remote tool. The server is the source of truth.

---

Minimal example

tools:
 - kind: MCPServer
 name: linear-tools
 url: https://mcp.linear.app/mcp
 auth:
 token:
 secret_value!: <encrypted>

That's the entire setup for a server that uses a static bearer token. The platform connects, discovers the tools, and exposes them to the agent.

---

Authentication modes

MCP servers in ArchAgents support three authentication patterns. Pick the one that matches the server you're connecting to.

Static bearer token

The simplest option. Use it when the server accepts a long-lived API key or personal access token.

auth:
 token:
 secret_value!: <encrypted>

The token is encrypted at rest and only decrypted when the platform makes a request to the server.

OAuth 2.0

For services that require OAuth, declare an OAuth client and the platform handles the authorize, token-exchange, and refresh flow per user. The agent picks up the right token automatically.

auth:
 type: bearer
 client:
 kind: OAuthClient
 authorize_url: https://accounts.google.com/o/oauth2/v2/auth
 token_url: https://oauth2.googleapis.com/token
 client_id:
 secret_value!: <encrypted>
 client_secret:
 secret_value!: <encrypted>
 scopes:
 - https://www.googleapis.com/auth/calendar
 pkce: true

If the server publishes an OpenID Connect discovery document or supports dynamic client registration, you can omit authorize_url/token_url/registration entirely. The platform discovers them at connection time. Servers that publish a .well-known/oauth-authorization-server endpoint work this way.

Script-based auth

For service-account flows or anything else that needs custom logic to mint a token, point the auth at a script. The script runs at request time and must return a bearer token string.

auth:
 type: bearer
 client:
 kind: ScriptAuthClient
 script: |
 let jwt = import("jwt")
 let http = import("requests")
 let claims = {
 iss: $.client_email,
 scope: $.scope,
 aud: "https://oauth2.googleapis.com/token",
 iat: datetime.unix(),
 exp: datetime.unix() + 3600
 }
 let signed = unwrap(jwt.sign(claims, $.private_key, "RS256"))
 let resp = unwrap(http.post("https://oauth2.googleapis.com/token", {
 body: "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=" + signed,
 headers: {"Content-Type": "application/x-www-form-urlencoded"}
 }))
 resp.body.access_token
 data:
 client_email:
 secret_value!: <encrypted>
 private_key:
 secret_value!: <encrypted>
 scope: "https://www.googleapis.com/auth/cloud-platform"

Use the script when no built-in auth mode covers the server's flow, for example, JWT bearer assertions for Google service accounts or signed-request schemes used by older enterprise tools.

---

Connecting to existing integrations

When you already have an integration credential for a service (because you connected it through ArchAgents Portal or archagent authorize agentinstallation), the MCP server can reuse that credential instead of asking for tokens again.

In ArchAgents Portal, open the agent's tool configuration, choose MCP server, and pick the existing integration from the picker. ArchAgents Portal wires the connection and shows the discovered tools without you copying tokens around.

This is the cleanest setup for servers like GitHub, Slack, or Google services where the integration credential already exists for other purposes.

---

Other fields

- kind: MCPServer
 name: my-tools
 url: https://mcp.example.com/mcp
 auth:
 token:
 secret_value!: <encrypted>
 headers:
 X-Custom-Header: "value"
 timeout: 30000

Field	Purpose
name	Human-readable identifier shown in logs and the portal
url	The MCP server endpoint URL
auth	One of the three authentication modes above
headers	Additional HTTP headers attached to every request
timeout	Request timeout in milliseconds (default: 30000)

name and url are required. Everything else is optional.

---

Where MCP fits with other tool kinds

MCP is one of several tool kinds the platform supports:

Tool kind	When to use
Builtin	The platform already provides the capability (search, knowledge, memory, computer use)
Custom (script or workflow)	You need to call your own product logic from the agent
MCP server	You want a third-party tool server's full capability without defining each tool

You can mix them on the same agent. An agent can have a builtin search tool, a custom workflow-backed validation tool, and one or more MCP servers, all available at the same time.

---

Reviewing the discovered tools

After deploying an agent that uses MCP servers, inspect what the platform discovered:

archagent setup

Then invoke embed inside your coding agent:

# Claude Code
/agents:embed

# Codex
$archagents:embed

# Cursor
@archagents embed

The MCP-provided tools appear in the same list as builtin and custom tools. Each entry shows the tool name and a one-line description provided by the server.

This is the same operator workflow as for any other tool. See Tools for the full embed pattern.

---

Best practices

1. One MCP server per coherent capability set. Don't bundle unrelated tool surfaces into a single server.
2. Encrypt all credentials with secret_value!. Never paste plain tokens into config YAML.
3. Prefer integration-backed credentials over static tokens when the service already has an ArchAgents integration.
4. Review the discovered tool list before activation: the LLM will see every tool the server exposes, including ones you may not want it to call.
5. Set sensible timeouts. A slow MCP server stalls every agent message that reaches for one of its tools.

---

Where to go next

1. Tools: the underlying tool model and embed loop.
2. Extensions & Integrations: the broader external-system surface.
3. Field Guards: validate what an agent does with tool results before they reach the user.
4. Scripts: for the script-based auth mode and custom token minting.