External agents

An external agent (Cursor, Claude Code, Codex, or ChatGPT) connects to Fontana with one personal access token and acts as the Fontana agent you bind that token to. Fontana is a knowledge graph, an agent harness, and a workflow engine. The person invokes the bound agent by saying “Act as Echo, do X”, using that agent’s display name. The connection receives that agent’s tools, MCP instructions that introduce Fontana and then include the agent’s AGENT.md, and its granted skills as MCP prompts. Calls run as you, inside that agent’s permission ceiling.

Create a token

1. Sign in to your tenant Flow origin, for example https://acme.example.com.
2. Open Admin → Personal access tokens (/admin/access-tokens).
3. Create a token, give it a name, and choose the agent it is bound to.
4. Copy the full bearer (fnt_pat_…) from the create dialog. Fontana shows that value once.
5. Revoke a token on the same page when that bearer should stop connecting. Create another token when you need a new bearer, and bind it to an agent.

Each token is bound to one agent. You can hold several tokens, each bound to its own agent.

Fontana MCP URL

Point the client at one Streamable HTTP URL on your tenant origin:

https://<tenant>.<baseDomain>/_convex-site/mcp

For https://acme.example.com that URL is https://acme.example.com/_convex-site/mcp.

Send the bearer on every request:

Authorization: Bearer fnt_pat_…

The token must be created on the same tenant origin as this URL.

Copy the full token when you create it. The token page also has a client picker with a snippet for Cursor, Claude Code, Claude Desktop, ChatGPT, Claude.ai, GitHub Copilot, Codex, Hermes, and OpenClaw. Replace fnt_pat_… in these examples with that token.

Each snippet names the connection after the environment it reaches: fontana-prod, fontana-staging, fontana-dev. Keep those names when you connect one client to more than one environment, so each connection has its own entry and its own tools. Where a client asks for a display name, the token page gives one in the same pattern, such as Fontana Prod.

Cursor

Add a server to ~/.cursor/mcp.json or a project .cursor/mcp.json, then run Developer: Reload Window:

{
  "mcpServers": {
    "fontana-prod": {
      "url": "https://<tenant>.<baseDomain>/_convex-site/mcp",
      "headers": {
        "Authorization": "Bearer fnt_pat_…"
      }
    }
  }
}

Claude Code

claude mcp add --transport http fontana-prod https://<tenant>.<baseDomain>/_convex-site/mcp --header "Authorization: Bearer fnt_pat_…"

Claude Desktop

Claude Desktop reaches a remote URL through mcp-remote. Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "fontana-prod": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://<tenant>.<baseDomain>/_convex-site/mcp",
        "--header",
        "Authorization: Bearer fnt_pat_…"
      ]
    }
  }
}

ChatGPT and Claude.ai

In ChatGPT, open Settings → Apps & Connectors, turn on developer mode, and add a custom connector. In Claude.ai, open Settings → Connectors and add a custom connector. Set the URL to https://<tenant>.<baseDomain>/_convex-site/mcp and send Authorization: Bearer fnt_pat_….

GitHub Copilot

In VS Code, add .vscode/mcp.json or open your user mcp.json:

{
  "servers": {
    "fontana-prod": {
      "type": "http",
      "url": "https://<tenant>.<baseDomain>/_convex-site/mcp",
      "headers": {
        "Authorization": "Bearer fnt_pat_…"
      }
    }
  }
}

Codex

Set FNT_PAT_PROD to the token, then add this to ~/.codex/config.toml:

[mcp_servers.fontana-prod]
url = "https://<tenant>.<baseDomain>/_convex-site/mcp"
bearer_token_env_var = "FNT_PAT_PROD"

Hermes

Add this to ~/.hermes/config.yaml:

mcp_servers:
  fontana-prod:
    url: "https://<tenant>.<baseDomain>/_convex-site/mcp"
    headers:
      Authorization: "Bearer fnt_pat_…"

OpenClaw

Add this under mcp.servers in ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "fontana-prod": {
        "url": "https://<tenant>.<baseDomain>/_convex-site/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer fnt_pat_…"
        }
      }
    }
  }
}

Instructions and skills

On connect, MCP instructions explain Fontana (knowledge graph, agent harness, workflow engine), name the agent this token acts as, and then include that agent’s AGENT.md.

Every connection has one extra tool, skills_read, so the client can read how a job is done before doing it:

Call	Returns
skills_read with no arguments	The skills the bound agent grants, each with its id and what it is for
skills_read with skill	That skill’s SKILL.md, then the list of its reference files
skills_read with skill and file	One reference file, such as a runbook or a template
skills_read with skill: "AGENT.md"	The bound agent’s own instructions and its own reference files

The same texts are also MCP prompts, for clients that show prompts to the person: AGENT.md, and one prompt per granted skill named by the skill’s catalog id.

Tools those skills allow are already in the tool list, under Flow tool ids such as mcp_session_open, mcp_ffs_put_file, workflow_startWorkflowRun, and mcp_knowledge-graph_kg_search.

Flow chat tools that open a skill session, delegate to another Fontana agent, or ask a person inside a Flow thread are not on this connection. The instructions say so. Call the tools that are listed.

Create agents, skills, and eval tests from a client

Agents, skills, and eval tests are files, so a client creates them by writing files with the Fontana Files tools. The instructions for each are a skill the client reads first with skills_read:

To do this	Read this skill first	Then
Create or change an agent	system/skills/agent-authoring	Write agents/<slug>/AGENT.md and any reference files with mcp_ffs_put_file
Create or change a skill	system/skills/skills-admin	Write skills/<name>/SKILL.md and any reference files with mcp_ffs_put_file
Set up and run an eval test	system/skills/evals-pages and its reference file references/eval-md.md	Write evals/<slug>/EVAL.md, then call evals_startRun and evals_getRun

A write of AGENT.md, SKILL.md, or EVAL.md answers with a second line: derive: ok when Fontana accepted the file, or derive error: … naming what to fix.

These need a token bound to an agent that grants the three skills and the Fontana Files tools. Echo does. See Author agents, Skills, and Evals.

Narrow what a token can do

The token can call what its agent can call. To give a client a smaller set, create an agent with the permissions, abilities, and skills you want, then bind the token to that agent. Another token can stay bound to a wider agent.

When the client gets 401

A 401 means Fontana does not accept the bearer.

Symptom	Cause	What you do
401 on the MCP URL	The bearer is unknown	Copy the full fnt_pat_… from a token you created on this tenant’s Personal access tokens page
401 after a token worked	The token was revoked	Create a new token on /admin/access-tokens, bind it to an agent, and update the client
401 with a token from another hostname	The token belongs to a different tenant origin	Create the token on the same origin as the MCP URL

Knowledge Graph and Fontana Files

The same bearer is accepted on the Knowledge Graph and Fontana Files MCP URLs. Each of those URLs serves only the tools the bound agent grants.

Surface	URL	Tool names
Fontana MCP	https://<tenant>.<baseDomain>/_convex-site/mcp	Flow tool ids
Knowledge Graph	https://<tenant>.<baseDomain>/_kg-engine/mcp	Short names such as kg_search
Fontana Files	https://<tenant>.<baseDomain>/_fontana-files/mcp	Short names such as put_file

Setup for those two URLs is on their pages. The token, the bound agent, and the 401 causes are the same.