MCP Servers

MCP servers are external services that expose AI tools through the open Model Context Protocol. AgentPress connects to them at runtime and lets your agents call those tools alongside their built-in toolset.

Typical examples: Firecrawl for web scraping, HubSpot for CRM data, Zapier for cross-app automation, an internal company service you host yourself.

Quick start

1. Open Admin → MCP Servers.
2. Pick a server from the Popular Servers grid, or click Add MCP Server to configure a custom one.
3. Fill in the connection URL, transport type, and any required credential.
4. Click Test to verify the server responds and reports its tool list.
5. Click Save — the server connects in the background and becomes available to agents.
6. Open any agent → MCP Servers tab → toggle the server on for that agent, and optionally pick which specific tools the agent can use.

That's it. Once enabled on an agent, the model will call MCP tools the same way it calls built-in ones.

Popular servers

The MCP Servers page includes a curated set of templates with pre-filled URLs and transport types. Click any card, fill in the API key when required, and the rest is prepared for you:

These templates are community-curated — their underlying URLs may change when the upstream provider updates their service. If a template stops working, check the provider's own docs and update the URL in the server's edit dialog.

Credentials

When an MCP server needs an API key, AgentPress stores it in the Org Credentials vault, not on the MCP row itself. That means:

• Multiple MCP servers can share one credential (e.g. two HubSpot integrations hitting different portals with the same access token).
• Rotating a key updates every MCP using it at once.
• Deleting the MCP server does not delete the credential — it stays in the vault for reuse. If you want it gone, delete it from the Credentials page separately.

The managed-server templates (Firecrawl, HubSpot, Zapier, etc.) auto-create the credential for you the first time you enter the key. Subsequent edits update the same credential in-place.

Per-agent tool selection

Opening a server from an agent's MCP Servers tab shows the server's full tool list. You can enable a subset of tools for that specific agent — useful when one agent should only read from a service and another should write.

If you leave the enabled-tools list empty, every tool on the server becomes available to that agent.

Connection status

Each MCP card shows one of four states:

• Connected (green) — handshake succeeded and the server reported at least one tool.
• Connected — no tools (amber) — the server accepted the connection but returned an empty tool list. Almost always a misconfiguration: wrong URL, wrong transport type, or incorrect auth. Fix the config and re-test.
• Failed (red) — connection or handshake failed. The error message is shown below the status pill — click it to copy the full text.
• Testing (blue) — connection attempt in progress.

Troubleshooting

"MCP URL rejected: …"

AgentPress refuses URLs that would reach into its own internal network (private IPs, loopback, the cloud-provider metadata endpoint, non-http schemes). This is a security guardrail, not a bug.

If you intentionally want to connect to an internal service:

• Deploy the service with a public DNS name and TLS.
• Make sure it's reachable from the internet (at least from AgentPress's outbound IP range).
• Private-network peering is not currently supported.

"Failed to retrieve credential"

The MCP row references a credential that no longer exists, or the credential's config is missing the template variable your URL needs (e.g. {{apiKey}}). Re-link a valid credential on the MCP server's edit dialog.

Tool calls fail inside a chat

First, confirm the server is still Connected on the MCP Servers page — click the refresh icon to retest.

If the server is healthy but individual tool calls fail, the problem is usually with the MCP server itself (rate limit, invalid credentials at the upstream API, server-side bug). Check the upstream provider's dashboard.

Server briefly connects then goes silent

Some MCP providers use SSE (Server-Sent Events) for server-to-client notifications. AgentPress supports SSE but not every provider implements the spec the same way. If you see GET SSE failed errors in your API logs for a server that otherwise works, it's typically safe to ignore — AgentPress treats them as informational, not fatal.

Security

• All MCP traffic is TLS-encrypted (AgentPress will not connect over plain http to public URLs).
• URL templates use {{placeholder}} syntax and are filled at connection time from the linked credential. Placeholders never appear in logs in their resolved form — the original template is logged instead.
• MCP rows are org-scoped: admins in other orgs on the same deployment cannot see, edit, or call your servers.
• Per-agent tool selection is enforced at the agent-configuration layer; the model physically cannot call a tool the admin didn't enable for the agent.

Adding a custom server (not in the popular list)

1. Click Add MCP Server on the MCP Servers page.
2. Enter a Name (unique per org), the Connection URL, and a Description if you want.
3. Choose Transport Type: Streamable HTTP for the modern spec, SSE if the provider requires the legacy transport.
4. If the server needs auth, click Link Credential and either pick an existing one or create a new one. Managed templates auto-create it; custom servers do not.
5. Click Test before saving — this verifies the URL is reachable and lists the tools the server exposes.
6. Click Save. The server connects in the background; the card updates to Connected within a few seconds.