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 stores the server name, transport, and command or URL in agent_setups.json. Omit filesystem or --command to be prompted for those values interactively.

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

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
`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.

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 require an OAuth handshake before the agent can call any tool. Register an OAuth app once on the provider side, then declare its credentials under the transport's oauth_client block:

{
  "oauth_client": {
    "server_url": "https://mcp.example.com/",
    "client_id": "<Provider client ID>",
    "client_secret": "<Provider client secret>",
    "client_metadata": {
      "client_name": "Zeta Alpha Agent",
      "scope": "read write",
      "grant_types": ["authorization_code", "refresh_token"],
      "response_types": ["code"],
      "token_endpoint_auth_method": "client_secret_post",
      "redirect_uris": [
        "https://<your-platform-api-host>/v0/service/mcp/oauth/callback"
      ]
    }
  }
}

redirect_uris must match the URI registered on the provider byte-for-byte (including any trailing slash). Tokens are stored per user — each end user goes through the consent the first time they trigger a tool.

For provider-specific walkthroughs see Connecting MCP Servers: HubSpot, GitHub, Google Workspace, Slack.

info

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

Add an MCP Server​

Example: Filesystem Server​

List and Manage Servers​

Configure Provider Settings​

Transport Options​

OAuth Client Registration​