How to Use MCP Tools

🔧 Tools

MCP (Model Context Protocol) lets your agent connect to external tool servers. You can add MCP servers that provide domain-specific APIs, file system access, database tools, or any other functionality exposed via the MCP specification.

Add an MCP Server

za agents capabilities mcp-servers add filesystem \
  --transport stdio \
  --command "npx -y @modelcontextprotocol/server-filesystem /Users/me/Desktop /Users/me/Downloads"

The CLI writes the server to mcp_configurations.json (next to agent_setups.json) and adds a mount for it to the agent's mcp_tools_provider_configuration, so several agents can use one server by name. Omit filesystem or --command to be prompted for those values interactively.

Flag	Description
--transport, -t	stdio (default), sse or http
--command	Command to run, for stdio
--url	Server URL, for sse and http
--description	What the server is for; the agent reads it to decide when to use the server
--header-secret HEADER=SECRET	Send HEADER with the value of the secret SECRET from env/secrets.json; repeat for several headers
--agent	The agent to mount the server in; default: the project's agent

za agents capabilities mcp-servers add tickets \
  --transport http --url https://mcp.example.com/mcp \
  --description "The support team's ticket system" \
  --header-secret Authorization=tickets-token

Example: Filesystem Server

za agents capabilities mcp-servers add filesystem \
  --transport stdio \
  --command "npx -y @modelcontextprotocol/server-filesystem /Users/me/Desktop /Users/me/Downloads"

This launches the official filesystem MCP server, giving the agent file read/write/search tools scoped to the specified directories.

List and Manage Servers

za agents capabilities mcp-servers list
za agents capabilities mcp-servers show filesystem
za agents capabilities mcp-servers remove filesystem
za agents capabilities mcp-servers settings
za agents capabilities mcp-servers connect tickets
za agents capabilities mcp-servers explore filesystem

Command	What it does
connect <name>	Connects a server from mcp_configurations.json for the local user and stores its tool listing in .mcp_oauth_integrations.json, as the chat's connect action does. An OAuth server prints an authorization URL; authorize, then run the command again.
explore [<name>]	Connects to a server, prints its tools with their input schemas, and disconnects without storing anything. Takes a configured name, or an ad-hoc server via --url or --command (with --transport). --call <tool> --args '<json>' invokes one tool after listing. OAuth servers are not supported.

Filter a Server's Tools

An entry in mcp_configurations.json takes its own include_tools and exclude_tools, which apply to every agent that mounts the server. They use namespaced names (<server>__<tool>), like the provider's lists. A mount's include_tools and exclude_tools narrow the server for one agent and use the server's own tool names.

[
  {
    "name": "tickets",
    "transport": "streamable-http",
    "transport_config": {"streamable_http": {"url": "https://mcp.example.com/mcp"}},
    "exclude_tools": ["tickets__delete_ticket"]
  }
]

{
  "mcp_tools_provider_configuration": {
    "enabled": true,
    "mounts": [{"name": "tickets", "include_tools": ["search_tickets", "get_ticket"]}]
  }
}

A tool reaches the agent only if it passes all three filter levels: the provider's, the server entry's, and the mount's.

Configure Provider Settings

za agents capabilities mcp-servers settings

Setting	Type	Default	Description
client_session_timeout_seconds	float	2	Read timeout for MCP client setup (initialize + list_tools); kept short so a slow server fails fast during connect.
tool_call_timeout_seconds	float	30	Read timeout for individual MCP tool calls.
convert_schemas_to_strict	bool	false	Enforce strict JSON schema on tool inputs
mounts	list	[]	The named servers the agent uses, from mcp_configurations.json (or the tenant's MCP servers on the platform). Each mount takes a name, optional include_tools/exclude_tools with the server's own tool names, and an optional defer_tools that overrides the provider's for that server.
servers	list	[]	Inline server definitions; prefer mounts.
selected_servers	list	null	The servers a user picked, sent in a request's bot_params. Only narrows the agent's servers; an unknown name is ignored.
defer_tools	bool	false	Load the servers' tools on demand: the model sees each server by name and description and loads its tools through tool search. A mount's own defer_tools overrides it.
confirmation_default	str	none	Which tools ask the user first by default: none, non_read_only (every tool the server does not annotate as read-only) or all. It holds only where no tool rule decides.
include_servers	list	null	Allowlist of MCP server names; when set, only these servers are activated.
exclude_servers	list	null	Denylist of MCP server names; always wins over include_servers.
include_tools	list	null	Allowlist of namespaced tool names (server__tool); when set, only these tools are exposed.
exclude_tools	list	null	Denylist of namespaced tool names (server__tool); wins over include_tools.

Tool names are namespaced as <server>__<tool> so two servers can expose the same tool name without clashing; use that qualified form in include_tools and exclude_tools. Server filters run first (a server dropped by include_servers/exclude_servers contributes no tools), then the tool filters apply to what remains. Excludes always win over includes, and an include_* allowlist, once set, hides everything not on it.

When the Agent Connects

A turn never dials servers up front. The agent's tool list comes from each server's stored listing, and a server is connected only on its first tool call in the turn; that call lists the tools again, which keeps the stored listing current, as does a server's tools/list_changed notification while the session is open. A server without a stored listing appears to the model as a single tool, mcp_oauth_connect_<server>, which connects it (or returns the authorization URL); once connected, its tools join the same turn. A change to a server's transport, endpoint, or OAuth sign-in settings (authorization server, client id, scope) invalidates its stored listing, so the server shows as the connect tool again until it is reconnected. Reconnecting drops tokens the user obtained under the old settings. In the Navigator, each user connects servers and refreshes their listings from Connected apps, see Connecting from the Navigator.

My Documents Files in Tool Calls

A model cannot pass a file's bytes in a tool call. With my_documents_argument_resolver_configuration enabled, the agent writes my-documents://<document_id> in a call's arguments instead, and the reference is replaced with the My Documents file's content, base64-encoded, right before the call reaches the server. Only the servers in server_names receive file content; in any other server's call the reference stays as written.

Setting	Type	Default	Description
enabled	bool	false	Replace my-documents://<document_id> in MCP tool arguments with the file's content
server_names	list	[]	The MCP servers whose tool calls may receive file content

Transport Options

Transport	Use case
stdio	Launch a local process (npx, python, etc.)
http-sse	Connect to a remote MCP server via HTTP/SSE
streamable-http	Connect via the newer Streamable HTTP transport

For HTTP transports, you can add custom headers for authentication and configure timeouts.

OAuth Client Registration

Hosted MCP servers sign each user in with OAuth; tokens are stored per user. Adding a Server to the Tenant owns the OAuth client configuration: the sign-in fields, the oauth_client block the platform derives, and the callback URL. Secrets are referenced by name, never written as values: client_secret_ref and headers_refs name a tenant secret, or, in a local mcp_configurations.json, a secret in env/secrets.json.

Provider walkthroughs: HubSpot, GitHub, Google Workspace, Slack, Atlassian, Microsoft 365.

info

For more details on MCP, visit the Model Context Protocol website.