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

# Execute MCP Tool

> Executes a tool directly on an MCP server configured by the authenticated user.

Executes a tool directly on an MCP server configured by the authenticated user.

## Usage

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.splox.io/api/v1/mcp-tools/execute \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "mcp_server_id": "0199e001-a23b-7c8d-1234-567890abcdef",
      "tool_slug": "search_documents",
      "args": {
        "query": "latest release notes"
      }
    }'
  ```

  ```python Python theme={null}
  from splox import SploxClient

  client = SploxClient(api_key="YOUR_API_KEY")
  result = client.mcp.execute_tool(
      mcp_server_id="0199e001-a23b-7c8d-1234-567890abcdef",
      tool_slug="search_documents",
      args={"query": "latest release notes"},
  )

  print(result.is_error)
  print(result.result.content)
  ```

  ```typescript Node.js theme={null}
  import Splox from "splox";

  const client = new Splox("YOUR_API_KEY");
  const result = await client.mcp.executeTool({
    mcp_server_id: "0199e001-a23b-7c8d-1234-567890abcdef",
    tool_slug: "search_documents",
    args: { query: "latest release notes" },
  });

  console.log(result.is_error);
  console.log(result.result.content);
  ```

  ```go Go theme={null}
  client := splox.NewClient("YOUR_API_KEY")
  result, err := client.MCP.ExecuteTool(ctx, splox.ExecuteToolParams{
      MCPServerID: "0199e001-a23b-7c8d-1234-567890abcdef",
      ToolSlug:    "search_documents",
      Args: map[string]any{
          "query": "latest release notes",
      },
  })
  if err != nil {
      panic(err)
  }

  fmt.Println(result.IsError)
  fmt.Println(result.Result.Content)
  ```
</CodeGroup>

## Request Body

| Field           | Type          | Required | Description                                                                          |
| --------------- | ------------- | -------- | ------------------------------------------------------------------------------------ |
| `mcp_server_id` | string (uuid) | Yes      | ID of the user MCP server to execute against. Must belong to the authenticated user. |
| `tool_slug`     | string        | Yes      | Tool name/slug to execute on that MCP server.                                        |
| `args`          | object        | No       | Tool input arguments. Defaults to an empty object.                                   |

## Response

```json theme={null}
{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 3 matching documents"
      }
    ],
    "isError": false
  },
  "is_error": false
}
```

## Notes

* This endpoint executes synchronously and returns the tool result in the HTTP response.
* The response `result` object is passed through from the MCP server and may include fields like `content`, `structuredContent`, and `isError`.
* Rate limit: **30 requests per minute** per authenticated user.


## OpenAPI

````yaml POST /mcp-tools/execute
openapi: 3.1.0
info:
  title: Splox API
  description: >-
    Run workflows, manage chats, receive events, and monitor execution via the
    Splox API
  version: 1.0.0
  contact:
    name: Splox Support
    email: support@splox.io
    url: https://community.splox.io
servers:
  - url: https://app.splox.io/api/v1
    description: Production API
security: []
tags:
  - name: MCP
    description: Discover MCP servers, manage connections, and execute MCP tools
  - name: Workflows
    description: List, get, and inspect workflows, versions, and nodes
  - name: Workflow Requests
    description: Run workflows, monitor execution, and retrieve results
  - name: Events
    description: Receive external events via Event Hub webhooks
  - name: Chats
    description: Manage chat sessions for workflow interactions
paths:
  /mcp-tools/execute:
    post:
      tags:
        - MCP
      summary: Execute MCP Tool
      description: >-
        Executes a tool directly on an MCP server configured by the
        authenticated user.
      operationId: executeMCPTool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - mcp_server_id
                - tool_slug
              properties:
                mcp_server_id:
                  type: string
                  format: uuid
                  description: ID of the user MCP server to execute against
                tool_slug:
                  type: string
                  description: Tool name/slug to execute
                args:
                  type: object
                  additionalProperties: true
                  description: Tool input arguments
            example:
              mcp_server_id: 0199e001-a23b-7c8d-1234-567890abcdef
              tool_slug: search_documents
              args:
                query: latest release notes
      responses:
        '200':
          description: Tool executed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    description: Raw MCP CallTool result payload
                    properties:
                      content:
                        type: array
                        items:
                          type: object
                          additionalProperties: true
                      structuredContent:
                        description: Optional structured output from MCP tool
                        nullable: true
                      isError:
                        type: boolean
                    additionalProperties: true
                  is_error:
                    type: boolean
                    description: Convenience flag mirroring result.isError
              example:
                result:
                  content:
                    - type: text
                      text: Found 3 matching documents
                  isError: false
                is_error: false
        '400':
          description: Bad request — missing or invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: MCP server not found
        '429':
          description: Rate limit exceeded (max 30 per minute per user)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token generated from your Splox account settings. Create tokens at
        https://app.splox.io/account?tab=settings

````