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

# MCP Servers

```bash theme={null}
telnyx-acp add tool mcp --url https://mcp.deepwiki.com/mcp
```

```text theme={null}
✓ added tool deepwiki (MCP server https://mcp.deepwiki.com/mcp: 3 tools: deepwiki__ask_wiki_question, deepwiki__read_wiki_contents, deepwiki__read_wiki_structure for the model) — applied on next deploy
```

Any remote [Model Context Protocol](https://modelcontextprotocol.io) server over Streamable HTTP, by URL. This is the simple case, a server and an optional credential. For governed access, with authentication, access control and policy, use [Agent Gateway](/docs/agents/tools/agent-gateway).

`add tool mcp` connects, lists the server's tools and writes them, name, description and input schema, into `agent.json`, so the deployed agent never discovers at a cold start. The model sees each as `<name>__<tool>`, `deepwiki__read_wiki_structure` here. Every call goes from the agent's instance straight to the server; the session is kept while the instance is active, and opened again after an eviction or when the server answers 404.

| Flag | Meaning |
| - | - |
| `--url <url>` | The server's Streamable HTTP endpoint. Required. |
| `--name <name>` | The server's short name, the prefix of its tools and what `remove tool` takes. From the host by default: `mcp.deepwiki.com` gives `deepwiki`. Lowercase letters, digits and underscores, up to 32 characters, starting with a letter. |
| `--secret <NAME>` | The secret that authenticates to the server, sent as a bearer token in `Authorization`. |
| `--header <Header>` | Send the secret in this header instead, `X-API-Key` for example. |
| `--allow <a,b>` | Only these of the server's tools reach the model. A name the server does not list is refused with the ones it does. |

A credential is a secret like any other: the value is read from `.env` (or the environment) to list the tools and under `dev`, and from the platform secret once deployed, so `telnyx-acp add secret <NAME>` must store it before `deploy`; `validate` names a declared secret the project does not have. Deployed, the value is read at every call and never kept; `dev` reads `.env` as it starts.

```json theme={null}
"tools": [{
  "type": "mcp", "name": "deepwiki", "url": "https://mcp.deepwiki.com/mcp",
  "tools": [{ "name": "read_wiki_structure", "description": "…", "inputSchema": { "type": "object", "properties": { "repoName": { "type": "string" } } } }]
}]
```

Not covered: servers over stdio (a deployed function spawns nothing), OAuth flows to a server (a bearer token or an API-key header is the credential), and MCP resources, prompts and sampling.

The model sees each tool as `<name>__<tool>`, and the model APIs accept function names of at most 64 characters, so `add tool mcp` and `validate` refuse a combination that is longer, naming the tool and the room a shorter `--name` would leave, or `--allow` to leave it out. Each request to the server is bounded: 15 seconds for each set-up and list request, 30 seconds for each tool call, so one operation can take longer than either; a server that stalls or never closes its stream ends the call with an error naming the host. A tool's text result is cut at 12,000 characters, with `truncated: true`. A transport error names the host only; `add tool mcp` names the URL it was given when it cannot list the server, and a server's own error text is passed through.

## Refresh

```bash theme={null}
telnyx-acp tools --refresh
```

`--refresh` asks each MCP server for its tools again and rewrites the list in `agent.json`, for a server that gained or changed a tool. With several servers the list gets long; `telnyx-acp tools --file tools.json` moves it into its own file, and `agent.json` keeps a reference.

## Remove

```bash theme={null}
telnyx-acp remove tool deepwiki
```

An MCP server is removed by its name.