Custom MCP servers
Connect any MCP server by its address, and allow its tools one by one.
Any service with an MCP server over HTTP can be connected by its address. The server's tools become what agents can be allowed with it, each on its own. Successful tool calls, calls denied by access settings, and calls the server failed are written to the activity log, as with the built-in integrations.
Connect a server
Name it and enter the address
Open Connections and permissions, then Add connection, and the plus beside Custom MCP server. Give the
connection a name, such as "Company docs", which is what it is called in Personal Agent Proxy and
to agents (a right click on it in the connections list renames it later), and enter the server's
MCP address, such as https://mcp.example.com/mcp.
The server has to be reachable from the internet, over https. Hosted Personal Agent Proxy refuses
servers on private addresses, such as 10.0.0.7 or localhost, and holds the server's
authorization server to the same rule; a server on a private address needs Personal Agent Proxy
self-hosted beside it, with ALLOW_PRIVATE_HOSTS set, and may then be reached over
http.
The servers of the services Personal Agent Proxy connects itself, Granola,
Notion, Linear,
Cloudflare (https://mcp.cloudflare.com/mcp), Exa
and Parallel, are connected as those services, under the name you gave,
as adding them from the list of connections does: entering one's address opens the service's own
sign-in, or, for Cloudflare, Exa, Linear and Parallel with an access token typed in, or Exa's
address with its key in it (?exaApiKey=), connects the service with it as its API key. Granola and Notion are only
signed in to, so a token typed in for them is turned down. See also
When a server becomes built in.
Sign in, if the server asks
Personal Agent Proxy asks the server for its tools. A server that answers is connected at once. One
that asks for a sign-in opens its sign-in page, as Granola, Notion and Linear do; once you approve
access, it sends you back to the new connection. A server that takes a token or an API key instead
of a sign-in gets it from the Access token field, which is sent as a bearer token with every
request. A server that takes another scheme gets the value as written when it starts with the
scheme, such as Basic dXNlcjpwYXNz.
Review the tools
The connection's page lists the server's tools under Permissions, one checkbox each. Tools that say they only read are on from the start; the rest are off until you turn them on, for every agent on the connection's page or for one agent on the agent's page.
What agents can do
Each tool the server lists is an action of its own, allowed or not. An agent that may run a tool calls it with the params the server describes, and gets back what the tool answered, as the server wrote it. Nothing is copied: every call goes to the server.
A tool's risk comes from what the tool says about itself. One that says it only reads is low risk. One that changes something it says can be undone is medium, and one that says it can't be undone is marked high risk. A tool that says nothing about itself gets no risk label: it may do anything, so it starts off, but nothing is claimed about it either way.
The activity log shows each run by the tool's name, with the params the agent gave it.
A server's tools can change. The connection's page has a button that asks the server for its tools again and keeps the new list. A tool that appears later is off until you turn it on, and the settings for a tool the server no longer lists are dropped, so they can't carry over to a different tool the server later lists by that name.
How the sign-in works
Personal Agent Proxy signs in to a server the way the MCP specification lays out: the server says which authorization server its tokens come from, Personal Agent Proxy registers itself there as a client, and you approve access on the authorization server's own page. Tokens are refreshed as they run out. A server whose authorization server does not let clients register themselves cannot be connected this way; use an access token instead, where the server offers one.
When a server becomes built in
When Personal Agent Proxy starts connecting a service itself, a custom server you added for it becomes a connection of that service the next time Personal Agent Proxy starts. It keeps its name, its agents and its activity:
- Each of the service's actions is on, by default or for an agent, only where every tool it is made of was on, so nothing is allowed that wasn't before. Settings for tools the service has no action for are dropped.
- Tool runs in the activity log become the service's own requests, such as listing Linear issues or running a web search. Runs of tools it has no action for stay as they were.
- A server you signed in to stays signed in, and an access token typed in for Cloudflare, Exa, Linear or Parallel, or an Exa key in the server's address, becomes the connection's API key, once the service has accepted it. Any other token, one the service turns down, or a sign-in it has since revoked, doesn't carry over: the connection has to be signed in to before agents can use it, so open it and choose Sign in.
- A server you connected with no token or sign-in at all, as Parallel's free search server, stays a custom server, so it keeps working as it did.