> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Agent Tool

> Attach a tool to an agent (action, custom_function, mcp, agent, or workflow). The API handles catalog resolution and graph wiring.

The request body is discriminated by `type`:

* `action` — `{ "type": "action", "connection_id": "...", "operation_ids": ["<catalog id>"] }`
* `custom_function` — `{ "type": "custom_function", "custom_function_id": "..." }`
* `mcp` (registry) — `{ "type": "mcp", "mcp_id": "<registry id>" }`
* `mcp` (inline) — `{ "type": "mcp", "url": "https://...", "name": "...", "transport": "streamable-http" }`
* `agent` (sub-agent) — `{ "type": "agent", "agent_id": "..." }`
* `workflow` — `{ "type": "workflow", "workflow_id": "..." }`


## OpenAPI

````yaml POST /v1/agents/{agent_id}/tools
openapi: 3.1.0
info:
  title: xpander.ai API Service
  description: |2-

        The xpander.ai API Service provides a unified REST API for managing AI agents,
        executing tasks, managing knowledge bases, and integrating with external systems.
        
        Features:
        - Agent Management: Create, update, deploy, and delete AI agents
        - Task Execution: Invoke agents with support for sync, async, and streaming modes
        - Knowledge Bases: Manage knowledge bases and documents for RAG workflows
        - Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
        - MCP Integration: Model Context Protocol support for standardized AI interactions
        
        Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer <jwt>`).
        
  version: '0.001'
servers:
  - url: https://api.xpander.ai
security: []
paths:
  /v1/agents/{agent_id}/tools:
    post:
      tags:
        - API v1
        - Agents
        - Agent Tools
      summary: Add Agent Tool
      description: >-
        Attach a tool to an agent (action, custom_function, mcp, agent, or
        workflow). The API handles all catalog resolution and graph wiring.
      operationId: Add_agent_tool_v1_agents__agent_id__tools_post
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            title: Agent Id
        - name: deploy
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Deploy the agent after adding so the change takes effect
              immediately.
            default: true
            title: Deploy
          description: >-
            Deploy the agent after adding so the change takes effect
            immediately.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/AddActionTool'
                - $ref: '#/components/schemas/AddCustomFunctionTool'
                - $ref: '#/components/schemas/AddMcpTool'
                - $ref: '#/components/schemas/AddSubAgentTool'
                - $ref: '#/components/schemas/AddWorkflowTool'
              discriminator:
                propertyName: type
                mapping:
                  action:
                    $ref: '#/components/schemas/AddActionTool'
                  custom_function:
                    $ref: '#/components/schemas/AddCustomFunctionTool'
                  mcp:
                    $ref: '#/components/schemas/AddMcpTool'
                  agent:
                    $ref: '#/components/schemas/AddSubAgentTool'
                  workflow:
                    $ref: '#/components/schemas/AddWorkflowTool'
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentTool'
                title: Response Add Agent Tool V1 Agents  Agent Id  Tools Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    AddActionTool:
      properties:
        type:
          type: string
          const: action
          title: Type
          default: action
        connection_id:
          type: string
          title: Connection Id
          description: Connector connection id (the connection to call through).
        operation_ids:
          items:
            type: string
          type: array
          title: Operation Ids
          description: >-
            Operation catalog ids — the `id` field from GET
            /tools/connectors/{connector_id}/operations.
      type: object
      required:
        - connection_id
        - operation_ids
      title: AddActionTool
      description: Attach connector operations as agent tools.
    AddCustomFunctionTool:
      properties:
        type:
          type: string
          const: custom_function
          title: Type
          default: custom_function
        custom_function_id:
          type: string
          title: Custom Function Id
          description: Custom function id.
      type: object
      required:
        - custom_function_id
      title: AddCustomFunctionTool
      description: Attach a custom function as an agent tool.
    AddMcpTool:
      properties:
        type:
          type: string
          const: mcp
          title: Type
          default: mcp
        mcp_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Id
          description: >-
            MCP server id from the org registry — the `id` from GET
            /tools?type=mcp. Provide this OR `url`.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: >-
            Remote MCP server URL for an inline (non-registry) MCP. Provide this
            OR `mcp_id`.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Display name for an inline MCP.
        transport:
          anyOf:
            - $ref: '#/components/schemas/MCPServerTransport'
            - type: 'null'
          description: Transport for an inline MCP.
          default: streamable-http
        auth_type:
          anyOf:
            - $ref: '#/components/schemas/MCPServerAuthType'
            - type: 'null'
          description: Auth type for an inline MCP.
          default: none
        api_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Api Key
          description: API key for an inline MCP when auth_type=api_key.
        allowed_tools:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allowed Tools
          description: Optional subset of the MCP server's tools to expose.
      type: object
      title: AddMcpTool
      description: >-
        Attach an MCP server — either from the org registry (mcp_id) or inline
        by URL.
    AddSubAgentTool:
      properties:
        type:
          type: string
          const: agent
          title: Type
          default: agent
        agent_id:
          type: string
          title: Agent Id
          description: Id of the agent to attach as a sub-agent.
      type: object
      required:
        - agent_id
      title: AddSubAgentTool
      description: Attach another agent as a callable sub-agent tool.
    AddWorkflowTool:
      properties:
        type:
          type: string
          const: workflow
          title: Type
          default: workflow
        workflow_id:
          type: string
          title: Workflow Id
          description: Id of the workflow to attach.
      type: object
      required:
        - workflow_id
      title: AddWorkflowTool
      description: Attach a workflow as a callable tool.
    AgentTool:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Stable handle for this attached tool. Pass it to DELETE to remove
            the tool.
        type:
          $ref: '#/components/schemas/AgentToolType'
          description: The kind of attached tool.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Human-readable tool name.
        connection_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connection Id
          description: Connector connection id. Actions only.
        operation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation Id
          description: Operation catalog id. Actions only.
        operation_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation Name
          description: OpenAPI operationId. Actions only.
        custom_function_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Custom Function Id
          description: Custom function id. Custom functions only.
        mcp_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Id
          description: MCP registry id. MCP only.
        allowed_tools:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allowed Tools
          description: Subset of MCP tools exposed. MCP only.
        target_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Id
          description: Referenced sub-agent or workflow id.
      type: object
      required:
        - id
        - type
      title: AgentTool
      description: >-
        A tool attached to an agent — the simplified, unified view of one graph
        entry.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MCPServerTransport:
      type: string
      enum:
        - stdio
        - sse
        - streamable-http
      title: MCPServerTransport
    MCPServerAuthType:
      type: string
      enum:
        - api_key
        - oauth2
        - custom_headers
        - none
      title: MCPServerAuthType
    AgentToolType:
      type: string
      enum:
        - action
        - custom_function
        - mcp
        - agent
        - workflow
      title: AgentToolType
      description: Type of a tool attached to an agent.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API Key for authentication
      in: header
      name: x-api-key

````