--- title: "Add Agent Tool" method: POST path: "/v1/agents/{agent_id}/tools" tags: ["API v1", "Agents", "Agent Tools"] --- # Add Agent Tool `POST /v1/agents/{agent_id}/tools` ## Request - Base URL: `https://api.xpander.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.xpander.ai/v1/agents/{agent_id}/tools` - Auth: API key in header `x-api-key` Attach a tool to an agent (action, custom_function, mcp, agent, workflow, or skill). The API handles all catalog resolution and graph wiring. ## Path parameters - `agent_id` string, required ## Query parameters - `deploy` boolean: Deploy the agent after adding so the change takes effect immediately. ## Request body - union - AddActionTool: Attach connector operations as agent tools. - `type` 'action' - `connection_id` string, required: Connector connection id (the connection to call through). - `operation_ids` string[], nullable: Operation catalog ids (the `id` field from GET /tools/connectors/{connector_id}/operations). Omit to attach every operation the connection exposes. - AddCustomFunctionTool: Attach a custom function as an agent tool. - `type` 'custom_function' - `custom_function_id` string, required: Custom function id. - `hitl_options` object, nullable: Human-approval settings the tool attaches with (same keys as the tool settings `hitl_options`), so it is never callable before its gate. - AddMcpTool: Attach an MCP server — either from the org registry (mcp_id) or inline by URL. - `type` 'mcp' - `mcp_id` string, nullable: MCP server id from the org registry — the `id` from GET /tools?type=mcp. Provide this OR `url`. - `url` string, nullable: Remote MCP server URL for an inline (non-registry) MCP. Provide this OR `mcp_id` OR `command`. - `mcp_type` 'local' | 'remote' - `command` string, nullable: Command that starts a local (stdio) MCP server inside the agent's workspace, e.g. 'npx -y @modelcontextprotocol/server-github'. Provide this OR `url` OR `mcp_id`. - `env_vars` object, nullable: Environment for a local MCP server. Use ${NAME} to reference a workspace secret; the value is resolved in the workspace and never stored on the agent. - `name` string, nullable: Display name for an inline MCP. - `transport` 'stdio' | 'sse' | 'streamable-http' - `auth_type` 'api_key' | 'oauth2' | 'custom_headers' | 'sso_user' | 'none' - `api_key` string, nullable: API key for an inline MCP when auth_type=api_key. - `client_id` string, nullable: OAuth2 client id for an inline MCP (optional; empty enables dynamic registration). - `client_secret` string, nullable: OAuth2 client secret for an inline MCP. - `additional_scopes` string[], nullable: Extra OAuth2 scopes for an inline MCP. - `share_user_token_across_other_agents` boolean, nullable: Share the authorized MCP token across the org's other agents. - `share_connection_with_other_users` boolean, nullable: OAuth2 MCP: a caller with no sign-in of their own runs on the agent owner's connection. Off when omitted. - `sso_token` string, nullable: auth_type=sso_user: 'access' or 'id' sends the user's SSO token as-is (org admins only), 'exchange' sends it exchanged for sso_audience. - `sso_audience` string, nullable: auth_type=sso_user with sso_token=exchange: the audience the user's SSO token is exchanged for. - `headers` object, nullable: Custom headers sent to an inline MCP. - `allowed_tools` string[], nullable: Optional subset of the MCP server's tools to expose. - `health_check_tool` string, nullable: A read-only tool with no required arguments that the connection check calls to prove tool calls work. - `health_check_error_text` string, nullable: Text in the health-check answer that means the call failed, for servers that do not flag errors. - `register_in_org_registry` boolean, nullable: Remote inline MCP only: also register this server as an org-shared registry entry and attach the agent to it by reference. - AddSubAgentTool: Attach another agent as a callable sub-agent tool. - `type` 'agent' - `agent_id` string, required: Id of the agent to attach as a sub-agent. - AddWorkflowTool: Attach a workflow as a callable tool. - `type` 'workflow' - `workflow_id` string, required: Id of the workflow to attach. - AddSkillTool: Attach a skill from the xpander skills catalog as an agent tool. - `type` 'skill' - `skill_name` string, required: Skill name — the `name` from GET /skills/catalog. ## Response `200` Successful Response - AgentTool[] - `id` string, required: Stable handle for this attached tool. Pass it to DELETE to remove the tool. - `type` 'action' | 'custom_function' | 'mcp' | 'agent' | 'workflow' | 'skill', required: Type of a tool attached to an agent. - `name` string, nullable: Human-readable tool name. - `connection_id` string, nullable: Connector connection id. Actions only. - `operation_id` string, nullable: Operation catalog id. Actions only. - `operation_name` string, nullable: OpenAPI operationId. Actions only. - `use_mock` boolean, nullable: Operation serves AI-generated mock data instead of the real API. Actions only. - `connector_auth_mode` string, nullable: Binding auth mode: 'autonomous' (connection credential) or 'user_authentication' (each caller signs in). Actions only. - `connector_share_user_token` boolean, nullable: Whether a user's authorized connector token is shared across the org's other agents. Actions only. - `connector_write_mode` string, nullable: What happens to a call that changes something: 'allow', 'ask' (a person approves it first) or 'block'. Actions only; None means allow. - `requires_approval` boolean, nullable: Whether a person must approve this action before it runs. Actions only; None means never configured. - `approval_rule` object, nullable: The stored approval rule for this action (approvers, channels, allowed scopes, on_deny), so a settings UI opens on real values. Never carries arguments or credentials. - `custom_function_id` string, nullable: Custom function id. Custom functions only. - `mcp_id` string, nullable: MCP registry id. MCP only. - `allowed_tools` string[], nullable: Subset of MCP tools exposed. MCP only. - `mcp_url` string, nullable: MCP server url. MCP only. - `mcp_type` string, nullable: MCP server type: remote (url) or local (command, hosted in the agent's workspace). MCP only. - `mcp_command` string, nullable: Command that starts a local MCP server. Local MCP only. - `mcp_env_vars` object, nullable: Environment of a local MCP server. A ${NAME} reference to a workspace secret is returned as written; a literal value is returned blank, the same way header values are. Local MCP only. - `mcp_auth_type` string, nullable: MCP auth type (api_key/oauth2/custom_headers/sso_user/none). MCP only. - `mcp_registry_id` string, nullable: Registry entry id when this MCP is attached from the shared org registry (editing it affects every agent). Absent for inline MCPs. MCP only. - `mcp_transport` string, nullable: MCP transport (streamable-http/sse/stdio). MCP only. - `mcp_registry_name` string, nullable: Name of the bound registry entry, read for every viewer, also when the entry is another member's personal one. Set by the agent tools list (GET /v1/agents/{id}/tools), not by the agent views. MCP only. - `mcp_registry_access_scope` string, nullable: Audience of the bound registry entry: personal or organizational. MCP only. - `mcp_registry_owner_name` string, nullable: Display name of the member who owns a personal registry entry. MCP only. - `mcp_headers` string[], nullable: Custom header names configured on the MCP (keys only; values are never returned). MCP only. - `mcp_client_id` string, nullable: OAuth2 client id for the MCP, if set. MCP only. - `mcp_additional_scopes` string[], nullable: Extra OAuth2 scopes for the MCP. MCP only. - `mcp_share_user_token` boolean, nullable: Whether the authorized MCP token is shared across the org's other agents. MCP only. - `mcp_share_connection` boolean, nullable: Whether a caller with no sign-in of their own runs this agent's OAuth MCP on the owner's connection. MCP only. - `mcp_sso_token` string, nullable: For mcp_auth_type sso_user: access, id or exchange. MCP only. - `mcp_sso_audience` string, nullable: For mcp_auth_type sso_user with exchange: the audience. MCP only. - `mcp_has_api_key` boolean, nullable: Whether an API key is stored for the MCP (the value is never returned). MCP only. - `mcp_has_client_secret` boolean, nullable: Whether an OAuth2 client secret is stored for the MCP (the value is never returned). MCP only. - `mcp_connection_status` string, nullable: Last probe outcome for the MCP: connected / tools_failing / auth_required / error. MCP only. - `mcp_tools_verified` boolean, nullable: True when the last probe's health-check tool call succeeded, so the tools are known to run. MCP only. - `mcp_last_error` string, nullable: Why the last probe did not report connected. MCP only. - `mcp_health_check_tool` string, nullable: The tool the health probe calls to prove calls work. MCP only. - `mcp_health_check_error_text` string, nullable: Text that marks a failed health-check answer. MCP only. - `mcp_tools_count` integer, nullable: Tool count discovered by the last probe. MCP only. - `mcp_last_checked_at` string, nullable: ISO timestamp of the last probe. MCP only. - `target_id` string, nullable: Referenced sub-agent or workflow id. - `skill_name` string, nullable: Skill name from the xpander skills catalog. Skills only. - `visible` boolean: False when the tool is authored hidden and must not be listed in the app; it stays attached and keeps running. ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/xpander/apis/xpander-ai-api-service.md) - [All operations](https://skmtc.dev/xpander/apis/xpander-ai-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/xpander/apis/xpander-ai-api-service/revisions/725c0066d5df?raw)