Custom MCP servers (advanced)

What this is

MCP — Model Context Protocol — is the open standard for connecting AI assistants to external tools. Built-in integrations like Xero, FreeAgent, Notion, and Linear are already MCP servers under the hood. Custom MCP support lets you connect any other MCP server — built by you, your team, or a third party — so the assistant can use its tools the same way it uses the built-in ones.

This is an advanced feature. If you've never run an MCP server before, you probably don't need it — the built-in integrations cover the consultancy use cases most people need. But if you have a custom internal tool, a niche SaaS your accountant uses, or a personal automation stack, this is how you wire it in.

The trust model

Three things to internalise before you connect a server:

• You're trusting this server. When the assistant calls one of its tools, it may include context derived from your data — account names, commitments, time entries — as arguments. Only connect servers you operate or trust.
• You decide what runs. Read-only tools (search, list, get) are usable as soon as the server is connected. Tools that change data ("write" tools) are off by default — you enable each one explicitly.
• You can disconnect anytime. Hitting Disconnect clears the stored credentials and stops all tool access immediately. The cached tool list disappears from the assistant's view on the next call.

Connect a server

1. On the Integrations page in Really Focus, scroll to the Custom MCP servers (advanced) section at the bottom and click Add server.

2. Fill in the form:

   • Display name — lowercase letters, numbers, underscores only (e.g. internal_crm). Really Focus prefixes this with custom_ so it can't collide with built-in integrations.
   • Server URL — the full HTTPS URL of the MCP endpoint (e.g. https://mcp.mydomain.com/rpc). Plain HTTP is rejected outside local development.
   • Authentication — None, Bearer token, or Custom header. For Custom header, give a header name (e.g. X-Api-Key) and the secret value.

3. Hit Connect. Really Focus validates the URL (more on what it rejects below), then immediately calls tools/list on your server to discover its tool surface.

4. If discovery succeeds, the card flips to Active and lists every tool the server reports, with each tool classified as read or write. Read tools are immediately usable. Write tools sit in the list with an "Off" toggle next to them until you opt in.

What gets rejected

The connect form runs a few checks to block obvious server-side request forgery attempts. If you see a validation error, one of these is the cause:

• Non-HTTPS URLs (except in local dev).
• IP-literal hosts like https://10.0.0.1/rpc or https://[::1]/rpc.
• Hostnames that resolve to private ranges — RFC 1918 (10.x, 172.16/12, 192.168.x), loopback (127.x), link-local (169.254.x including the AWS metadata endpoint), and IPv6 equivalents.
• Special hostnames like localhost, *.internal, *.local, or anything without a dot.
• Reserved prefixes — names starting with custom_ are blocked because Really Focus adds that prefix automatically.

If your server lives on a private network and you genuinely want to connect it, expose it via an authenticated tunnel like Cloudflare Access or ngrok with auth, so the public DNS name resolves to a public IP.

Read vs write: how Really Focus decides

The MCP spec doesn't include a "risk" field on tool definitions, so Really Focus has to infer one. The heuristic is simple and works in most cases:

• A tool name that starts with create_, update_, delete_, send_, post_, patch_, put_, remove_, archive_, move_, set_, add_, write_, publish_, or cancel_ is classified as write.
• A tool whose description contains words like "creates", "sends", or "deletes" is classified as write.
• Everything else is read.

If a destructive tool gets misclassified as read — for example, a tool called reconcile_account that actually makes changes — click Mark as write next to it. This upgrade is one-way: you can't downgrade it back. The safety net is deliberate. A misread risk that goes read→write is fine; the opposite would let the assistant call a destructive tool without your approval.

Allowlisting write tools

Each write tool has an Off / Allowed checkbox next to it. The assistant cannot call write tools that aren't allowed — they're not even visible to the language model. To enable one:

1. Find the tool in the server's card on the Integrations page.

2. Tick the checkbox. The assistant can now call this tool. Every call is logged in your audit trail with the call's arguments and result.

3. If you change your mind later, untick it. The tool becomes invisible to the assistant again on the next briefing.

Refresh and tool changes

Tool surfaces drift. A server author might rename, remove, or add tools. Really Focus handles this two ways:

• Daily auto-refresh. Once a day, Really Focus re-runs tools/list on every connected MCP server and updates the cached tool list.
• Manual refresh. Hit the Refresh button on the server's card to do this on demand.

If a tool that was in your allowlist disappears from the server, Really Focus strips it from the allowlist automatically and writes an audit-log entry. If the tool comes back later, you'll need to re-enable it explicitly — this is intentional, not a bug.

What happens when things go wrong

The assistant doesn't hide tools the moment a server has a hiccup — that would silently change its plan ("I can't do X" when X just timed out). Instead:

• A failed call writes a last_error on the integration and increments a failure counter.
• After three consecutive failures the integration flips to Error status, marked with an "unreachable since" timestamp. Tools stay visible to the assistant; calls keep being attempted.
• A single successful call flips it back to Active and resets the counter.
• Authentication failures (HTTP 401 / 403) flip immediately and prompt you to reconnect — they almost never resolve on their own.

Worked example

Say you've built a small MCP server for your studio's internal time-and-materials tracker. It exposes three tools: list_open_projects, get_project, and create_project_note.

1. You connect it as internal_studio with a Bearer token. Discovery classifies list_open_projects and get_project as read (immediately callable) and create_project_note as write (off by default).

2. You build a custom schedule: "Each Monday at 9am, list every open project from internal_studio and tell me which ones haven't had a note in 10 days." The assistant runs this without touching anything destructive, so no extra approval is needed.

3. Later you decide you trust the assistant to add notes too. You tick Allowed next to create_project_note. Now in Telegram you can say "Add a note to project Acme that we're waiting on the brand brief" and the assistant calls the tool. The call shows up in the audit log.

What's not happening

• No arbitrary API support. Custom MCP only — not OpenAPI specs, not raw HTTP, not webhooks. If you want those, build a small MCP wrapper that exposes typed tools.
• No marketplace yet. You're connecting servers you find or build. We may add a vetted directory later, but for now the trust is entirely on you.
• No OAuth flow built in. If your server needs an OAuth-issued token, complete the flow yourself and paste the token as a Bearer secret. Token rotation is your responsibility.
• No streaming responses surfaced to you. Really Focus reads the first JSON-RPC frame from the server and closes the connection. Long-running tools should return their result, not stream progress.

When to use this vs request an integration

If the thing you want to connect is mainstream (a popular SaaS, a common accounting tool, a well-known task manager), tell us rather than wire it up yourself. Built-in integrations get OAuth flows, automatic credential refresh, and tighter UX — and the more users want them, the sooner they land.

Custom MCP is the right answer for:

• Internal tools that will never be a Really Focus first-party integration.
• Self-hosted MCP servers exposing your own data (databases, file systems, internal dashboards).
• Experiments and one-offs — you can disconnect them in two clicks if they don't pull their weight.

What's next

• Schedules — pair a custom server with a scheduled briefing to get its data working for you on a cadence.
• Billing integrations — the same allowlist + audit model, applied to Xero and FreeAgent.
• Back to Getting started