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:

Organization MCP

For internal use within your organization. Requires organization-scoped API key authentication.

POST /v1/orgs/:orgId/toolsets/:slug/mcp

Public MCP

For external consumers accessing public toolsets. Requires an API key for usage tracking and rate limiting.

POST /v1/public/:orgSlug/:toolsetSlug/mcp

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:

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:

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):

{
  "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:

{
  "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:

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

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

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

3. Sandbox execution

   Jinba Toolbox executes the tool code in an isolated sandbox environment (E2B or Daytona). The published version of the tool is used.

4. Result returned

   The execution result — including output, logs, and any errors — is returned to the agent through the MCP response.

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 — Full endpoint reference
• SDK — Programmatic access via the TypeScript SDK
• Versioning & Publishing — How published versions are resolved