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

# MCP Integration

> Connect AI agents to Jinba Toolbox via the Model Context Protocol (MCP)

## Overview

Jinba Toolbox provides native **Model Context Protocol (MCP)** endpoints that expose your toolsets as MCP-compatible servers. This allows AI agents and LLM-based applications -- such as Claude Desktop, Cursor, and custom agent frameworks -- to discover and execute your tools through a standardized JSON-RPC interface.

Each MCP-enabled toolset becomes an MCP server. The endpoint accepts JSON-RPC requests conforming to the MCP specification and returns tool definitions, executes tools, and streams results.

## MCP Endpoints

Jinba Toolbox offers two types of MCP endpoints:

<CardGroup cols={2}>
  <Card title="Organization MCP" icon="building">
    For internal use within your organization. Requires organization-scoped API key authentication.

    ```
    POST /v1/orgs/:orgId/toolsets/:slug/mcp
    ```
  </Card>

  <Card title="Public MCP" icon="globe">
    For external consumers accessing public toolsets. Requires an API key for usage tracking and rate limiting.

    ```
    POST /v1/public/:orgSlug/:toolsetSlug/mcp
    ```
  </Card>
</CardGroup>

## Enabling MCP for a ToolSet

MCP must be enabled on a per-toolset basis. You can toggle it in the web console or through the API:

```bash theme={null}
curl -X PATCH https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/slack-tools \
  -H "Authorization: Bearer jtb_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "mcpEnabled": true }'
```

Or via the SDK:

```typescript theme={null}
await client.updateToolSet("slack-tools", { mcpEnabled: true });
```

## Connecting AI Agents

### Claude Desktop

Add a Jinba Toolbox MCP server to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "slack-tools": {
      "url": "https://toolbox-api.jinba.dev/v1/public/my-org/slack-tools/mcp",
      "headers": {
        "Authorization": "Bearer jtb_xxxxxxxxxxxx"
      }
    }
  }
}
```

### Cursor

In Cursor's MCP settings, add a new server using the streamable HTTP transport:

```json theme={null}
{
  "mcpServers": {
    "slack-tools": {
      "url": "https://toolbox-api.jinba.dev/v1/public/my-org/slack-tools/mcp",
      "headers": {
        "Authorization": "Bearer jtb_xxxxxxxxxxxx"
      }
    }
  }
}
```

### Custom Agent Integration

If you are building a custom agent, connect to the MCP endpoint using any MCP-compatible client library. The endpoint supports JSON-RPC over HTTP.

**Example using the MCP TypeScript SDK:**

```typescript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://toolbox-api.jinba.dev/v1/public/my-org/slack-tools/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer jtb_xxxxxxxxxxxx",
      },
    },
  }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log(tools);

// Call a tool
const result = await client.callTool({
  name: "post-message",
  arguments: {
    channel: "#general",
    text: "Hello from my AI agent!",
  },
});
console.log(result);
```

## How It Works

<Steps>
  <Step title="Agent discovers tools">
    The agent sends a `tools/list` JSON-RPC request to the MCP endpoint. Jinba Toolbox responds with the list of tools in the toolset, including their names, descriptions, and input schemas.
  </Step>

  <Step title="Agent calls a tool">
    When the agent needs to use a tool, it sends a `tools/call` request with the tool name and arguments. The request is validated against the tool's input schema.
  </Step>

  <Step title="Sandbox execution">
    Jinba Toolbox executes the tool code in an isolated sandbox environment (E2B or Daytona). The published version of the tool is used.
  </Step>

  <Step title="Result returned">
    The execution result -- including output, logs, and any errors -- is returned to the agent through the MCP response.
  </Step>
</Steps>

## Organization vs. Public Endpoints

| Aspect         | Organization Endpoint                | Public Endpoint                        |
| -------------- | ------------------------------------ | -------------------------------------- |
| URL pattern    | `/v1/orgs/:orgId/toolsets/:slug/mcp` | `/v1/public/:orgSlug/:toolsetSlug/mcp` |
| Authentication | Org-scoped API key                   | API key                                |
| Access scope   | Private and public toolsets          | Public toolsets only                   |
| Use case       | Internal agents, CI/CD               | External consumers, shared agents      |

## Authentication

Both MCP endpoints require a Bearer token in the `Authorization` header:

```
Authorization: Bearer jtb_xxxxxxxxxxxx
```

The API key determines:

* Which organization the request is associated with
* Usage tracking and credit consumption
* Rate limiting

## Best Practices

* **Enable MCP selectively** -- only activate MCP on toolsets that you intend to expose to AI agents.
* **Use the public endpoint** for external integrations and the organization endpoint for internal workflows.
* **Monitor usage** through the run history API to track which tools agents are calling and how frequently.
* **Publish a version** before exposing a toolset via MCP -- the endpoint executes the published version, not the draft.
* **Provide clear tool descriptions** -- AI agents rely on tool names and descriptions to decide which tool to invoke.

## Related

* [REST API](/en/pages/toolbox/developer/api) -- Full endpoint reference
* [SDK](/en/pages/toolbox/developer/sdk) -- Programmatic access via the TypeScript SDK
* [Versioning & Publishing](/en/pages/toolbox/advanced/versioning) -- How published versions are resolved