Custom MCP server

The Custom MCP server connector links Timothy to any MCP server that speaks streamable HTTP. The app describes it as “Any streamable-HTTP MCP endpoint”.

Use it for a provider that offers a hosted MCP endpoint but has no tile of its own.

What it enables

The connector adds the tools the server offers. Timothy lists them before you save, so you see what you get. The set can change when the server changes.

These tools are for chat only. Missions do not get them.

A tool keeps its own name when no other tool has that name. When a name would clash with a built-in tool or another server’s tool, it gets the connector name as a prefix. The add page shows the name each tool will get.

When the server has more tools than the “MCP tool index threshold” in Features, the agent first sees a short index and loads the tools it needs through an entry point named after the provider, such as notion_load_tool. The add page says when a server is above that threshold.

Tool names

Every tool of an MCP connector starts with its provider: Notion’s search becomes notion_search. The name never changes when you add or remove other connectors, and it can never take the name of one of Timothy’s own tools.

Connectors with the same provider share their tools. Connect two Notion workspaces and chat sees one notion_search that asks which account to use. Agents and approvals need no change when you add the second workspace. If the two servers describe a tool differently, for example after one of them updates, that tool stays apart for each connector as <name>_notion_search until they match again.

In an agent’s “Tools allowlist”, search allows every tool ending in _search from any provider, and notion_search allows only Notion’s. The connector page shows each connector’s “Tool prefix”.

A connector added before providers existed uses its own name as the prefix, so its tools keep the names they had.

What you need

The server’s streamable-HTTP endpoint address, or the JSON config the provider publishes. Servers that need a login use a bearer token or an OAuth sign-in; see Connect an MCP server with OAuth for the second.

A server that only runs as a local program (started with npx or python) can run in its own sandbox container; see Local MCP server.

Add the connector

1. Open Settings, “Connectors”, and pick the “Custom MCP server” tile under “Add a connector”.
2. In “URL or JSON config”, paste the server’s address or the provider’s JSON config. Timothy reads the common mcpServers shape and also accepts the inner object or a single entry, with the address in url, serverUrl or endpoint. If the config lists several servers, pick one under “Server”. An entry that starts a local program (it has a command) is set up as a Local MCP server. A bearer token in an Authorization header is moved into the token field and saved as a secret. A header with a placeholder such as ${API_KEY} must be replaced before you continue.
3. Check the “Name”. It comes from the config key and you can change it. “Provider” is optional: leave it empty and Timothy uses the server’s own name after the check. See Tool names.
4. Press “Check server”. Nothing is saved yet.
   • If the server asks for a token, a “Bearer token” field appears. Paste it and check again. The token is used only for the check until you add the connector.
   • If the server needs an OAuth login, “Client ID” and “Client secret” fields appear. Leave them empty unless the server needs them, then press “Connect with OAuth” and approve access on the server’s sign-in page. Tools are listed only after you connect, so set the agents’ allowlists under Agents afterwards. See Connect an MCP server with OAuth.
   • If the server cannot be reached, the page shows the network reason. A server on a private network must be on the outbound host allowlist in Settings.
5. Review the tools. Each row shows the name, the description, and whether the server says the tool is read-only. The server makes that claim and Timothy does not check it. Each row also shows the name chat will use, for example “as notion_search”.
6. Uncheck any tool you do not want. “Try it” opens a form for one tool, checks your arguments and shows the request Timothy would send. It does not run the tool; real calls happen in chat and ask for permission.
7. Under “Agents”, pick the agents that should get the checked tools, then press “Add connector”. Timothy saves the token as a secret, adds and enables the connector, and adds the checked tools to each chosen agent’s “Tools allowlist”. You can change the allowlists later under Agents.

Verify

Press “Test” on the connector’s card. A working connector shows “Connection OK” and the number of tools the server offers.

Review the tools later

Open the connector from the Connectors list. The “Tools” panel lists the tools from the last check with the server’s read-only claim and a checkbox per agent. Tick or untick an agent to add the tool to, or remove it from, that agent’s “Tools allowlist”. Only that agent changes.

Press “Re-probe” to check the server again with the stored token or OAuth session. Tools the server added since the last check are marked “new” and are not allowed anywhere yet. Tools the server removed are marked “removed” until the next check. If an OAuth session has expired, the panel asks you to reconnect.

A connector added before this panel existed, or connected with OAuth, shows “Not checked yet” until the first re-probe.

Let missions read a tool

Missions and automations never get an MCP connector’s tools on their own. The “Missions may read” checkbox in the “Tools” panel is your review: tick a tool and missions whose agent lists it can call it, the same way they call native read tools such as mail search.

Timothy does not use the server’s read-only claim for this. Read the tool’s description, decide whether a mission running unattended may call it, and tick only then. A mission still needs the tool on its agent’s “Tools allowlist” and, to run without a prompt, on its “Approval allowlist” under Agents.

The marks are bound to the tool list you reviewed. When a re-probe shows that the server changed its tools, every mark lapses: missions stop getting the tools, the panel says so, and “Confirm marks” re-applies them against the new list once you have looked at it. A tool the server removed drops out of the marks.

A server whose tools sit behind the tool index (see the “Test” note about load_tool) cannot be marked; its tools stay in chat.

Common errors

Message	What to do
The check says the server needs a token	Paste the server’s bearer token and check again.
The check says the server needs an OAuth login	Press “Connect with OAuth”. The endpoint must use https.
The check shows a network reason	Check the address, and add the host to the outbound host allowlist if it is on a private network.
“Connection failed:” with a 401 on the card later	The token was revoked. Edit the connector and set a new bearer token.