Tools and MCP

Tools are how agents act on your workspace: query data, edit workflows, search the Knowledge Graph, run canvas changes, call external systems, and complete governed procedures. Fontana exposes one unified catalog of built-in capabilities and Model Context Protocol (MCP) integrations. You assign tools per agent in AI → Agents; the model never receives open-ended access to your estate. Every invocation is audited for compliance review.

MCP

Use MCP to access external data sources, perform financial data lookups, or communicate directly with your firm's tooling.

Built-in tools

Built-in tools run server-side inside your workspace (Convex tenant). They do not require an external MCP server. You allowlist them per agent; Fontana executes them on the server and returns results into the same chat thread.

Typical built-in capabilities include:

Area	What agents can do
Workflows and data	List resources, query workflow configuration, inspect run datasets, and start workflow runs
Knowledge Graph	Search governed corpora, fetch documents by slug, and manage agent memory where permitted
Canvas	Query and mutate workflow graphs (nodes, edges, ports, and canvas config) through typed canvas tools, often via Skills playbooks
Documents	Create, read, update, and rename workflow documents (specs, design notes, reports) tied to a workflow
Chat orchestration	Ask humans structured questions (Human in the Loop), manage task lists, delegate to sub-agents, and hand off threads
Skills runtime	Activate and close skill sessions and read bundled skill files (`activate_skill`, `close_skill`, `read_skill_file`)
VFS file tools	Read and search the source file itself, not derived Knowledge Graph retrieval: `vfs_file_info`, `vfs_read` (ranged for large files), `vfs_grep`, and the opt-in `vfs_update`

Built-in tools are the default surface for day-to-day Flow work. Prefer them when the capability already exists in Fontana so execution stays in-tenant, audited, and aligned with RBAC.

vfs_file_info, vfs_read, vfs_grep, and vfs_update give an agent verbatim access to a source file on the unified workspace filesystem, for example filling in a template, reading a config file exactly as written, or grepping a large CSV, none of which need the derived graph. They are scope-aware (knowledge-graph or skills) and independent of the kg-engine data plane. Reads stay query-shaped rather than unbounded dumps: small files return bounded, token-capped content, large files use ranged byte or line windows, and binary files return metadata with a typed refusal instead of raw bytes. vfs_update writes a new file version (full replace or targeted string replacement) and is never bundled into a wildcard tool default; you enable it explicitly per agent, and every write is RBAC-checked and versioned through the same audit trail as manual edits. Use Knowledge Graph retrieval instead when you want hybrid search, tree-walk, or entity navigation over the derived graph rather than the file’s exact bytes.

MCP connections

Use MCP when an agent must reach an external system you operate: SaaS APIs, databases, search services, calculators, or firm-specific HTTP tool servers.

In AI → Tools, you register MCP connections (HTTP or SSE transport), test connectivity, and refresh the discovered tool list. Add new MCP starts from one connection object (name, type, url). You can paste a Cursor mcpServers (or servers) catalog and Fontana splits it into individual connections. Edit stays one MCP. Approved tools appear in the agent catalog under namespaced ids (mcp_<connectionSlug>_<toolName>). You can assign individual tools or a connection wildcard (mcp_<connectionSlug>.*) that expands against the cached snapshot at runtime.

You can also ask Fontana Agent (or Tools Agent on /ai/tools) to add, update, test, or remove MCP connections. Those built-in calls are tools_listMcpConnections, tools_getMcpConnection, tools_upsertMcpConnection, tools_deleteMcpConnection, tools_testMcpConnection, tools_importMcpConnections, tools_listMcpConnectionAgents, and tools_setMcpConnectionForAgent. They require agents:read / agents:write, return public connection fields only (no bearer tokens), and cannot finish hosted OAuth: create the OAuth connection, then Connect in the browser on AI → Tools.

On AI → Tools, each MCP card has an Agents column beside the discovered tools. You select or unselect agents there; that writes mcp_<slug>.* on the agent’s AGENT.md tools list, the same persist as the extra MCP tiles on the agent card. Seeded Knowledge, Channels, and Coding connections stay on their dedicated agent-card tiles, but you can still assign them from this column.

Topic	What you should know
Authentication	Bearer tokens and OAuth app credentials (including BYOK Client ID/Secret) are stored write-only in Vault and used only during discovery and execution
OAuth providers	Hosted flows (for example Notion-style MCP URLs) use browser OAuth with PKCE; redirect URIs are shown in the admin UI
Discovery	Tool lists refresh when you test a connection; assign tools only after a successful refresh
Transport	Remote HTTP/SSE only; local stdio MCP servers cannot run from Convex actions
Governance	Agent assignment is the approval boundary in V1; unassigned MCP tools are not callable

For external systems, Fontana acts as an MCP client: your agents call tools on servers you register. For Knowledge Graph specifically, Fontana also runs a first-party MCP server on kg-engine, so agents (and external MCP clients you choose to expose it to) reach capped chunk-centric evidence packages through kg_search, kg_open, kg_hop, kg_ontology, kg_entity_search, and kg_namespaces. See Knowledge Graph → MCP for that server’s tool catalog and namespace-ACL enforcement.

Configure tools for agents

Tool governance spans three admin surfaces that work together:

AI → Tools - register MCP connections, inspect schemas, refresh discovery, manage credentials, and assign the connection to agents from the inverse Agents column
AI → Agents - allowlist built-in and MCP tools for each persona. Each extra MCP connection you add appears as a Tools tile on the agent card, including connections whose last test failed or that have no discovered tools yet (Knowledge, Channels, and Coding keep their dedicated tiles). Advanced view still lists every tool and wildcard. Assign Skills packages on the same card
Skills (sidebar) - author and upload skill folders; each package can declare allowed-tools that expand only while a skill session is active

Skills can union additional tools for the duration of an active playbook without permanently widening an agent’s baseline allowlist.

OpenSandbox (isolated code execution)

When agents need to run commands, scripts, or exploratory code safely, OpenSandbox provides isolated execution on the platform cluster. Each workspace reaches OpenSandbox through a single shared MCP connection seeded at deploy time; sandboxes are ephemeral, TTL-bound, and scoped with per-workspace bearer authentication.

Agent (MCP) → OpenSandbox platform → Ephemeral sandbox pod

Exploratory compute stays separated from your tenant data plane while remaining available to allowlisted agents through the same audited tool pipeline as other MCP calls.

Audit and review

Every built-in and MCP tool invocation writes to tool-call audit records with protocol metadata, latency, and outcomes. Operators with appropriate permissions can review agent tool usage in Flow admin surfaces and correlate activity with the immutable audit trail where your deployment enables it. See Observability, Compliance evidence, and Security (OpenSandbox controls in Workspace isolation).

Tools, MCP, and Agent Interop

Integration	Connects agents to	Configure in
Built-in tools	Fontana workflows, data, canvas, Knowledge Graph, chat orchestration	Admin → Agents (plus Skills for temporary expansion)
MCP	External tool and context servers (HTTP/SSE)	Admin → Tools + Admin → Agents
Agent Interop	Peer agents on other platforms (A2A, ACP, and related protocols)	Admin → Agent Interop

Do not confuse MCP tool servers with peer-agent federation. For delegation and handoff between agents, see Agent Interop.