MCP Integration

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 (Streamable HTTP transport). The endpoint accepts JSON-RPC requests conforming to the MCP specification, returns tool definitions and executes tools. It serves the toolset’s active published version — publish a version first.

MCP Endpoints

Jinba Toolbox offers two types of MCP endpoints:

Organization MCP

For internal use within your organization. Requires your organization’s API key (or a signed-in session). Falls back to the latest version if the environment has no active version.

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

Public MCP

For external consumers accessing public toolsets. Requires any valid API key; the credit cost is charged to the caller’s organization. :orgId is the provider organization’s canonical ID.

POST /v1/public/:orgId/: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.io/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

The console’s MCP Connection card (Tools tab of an MCP-enabled ToolSet) provides a ready-made Claude Desktop configuration that bridges the Streamable HTTP endpoint through the supergateway stdio bridge. Add it to claude_desktop_config.json and replace $JINBA_API_KEY with your key:

{
  "mcpServers": {
    "my-org-slack-tools": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--streamableHttp",
        "https://toolbox-api.jinba.io/v1/orgs/{orgId}/toolsets/slack-tools/mcp",
        "--header",
        "Authorization: Bearer $JINBA_API_KEY"
      ]
    }
  }
}

For a public ToolSet the card uses the /v1/public/{orgId}/slack-tools/mcp URL instead.

Cursor

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

{
  "mcpServers": {
    "slack-tools": {
      "url": "https://toolbox-api.jinba.io/v1/public/{orgId}/slack-tools/mcp",
      "headers": {
        "Authorization": "Bearer jtb_xxxxxxxxxxxx"
      }
    }
  }
}

Jinba App

The Connect with JinbaApp button on the same card creates (or reuses) an API key for the chosen environment and opens Jinba App with the MCP server pre-configured.

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.io/v1/public/{orgId}/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

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 — the tool slug as name, its display name as title, its description, and its input and output schemas.

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 arguments are validated against the tool’s input schema, and the caller organization’s credit balance is checked (one credit per call).

Sandbox execution

Jinba Toolbox executes the tool code in an isolated sandbox environment (E2B or Daytona). The active published version of the tool is used, and a Run record is created.

Result returned

The tool’s output (or an error) is returned to the agent as JSON text content in the MCP response; isError is set when the execution failed. Logs are available on the run’s detail page, not in the MCP response.

Organization vs. Public Endpoints

Aspect	Organization Endpoint	Public Endpoint
URL pattern	`/v1/orgs/:orgId/toolsets/:slug/mcp`	`/v1/public/:orgId/:toolsetSlug/mcp`
Authentication	Your organization’s API key or session	Any organization’s API key
Access scope	Your own private and public toolsets	Public toolsets of any organization (private ones only with the owning organization’s key)
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 (the caller organization recorded on the run)
Which organization’s credits are consumed
Which ToolSet environment (variables and active version) is used

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.

REST API — Full endpoint reference
SDK — Programmatic access via the TypeScript SDK
Versioning & Publishing — How published versions are resolved

​Overview

​MCP Endpoints

Organization MCP

Public MCP

​Enabling MCP for a ToolSet

​Connecting AI Agents

​Claude Desktop

​Cursor

​Jinba App

​Custom Agent Integration

​How It Works

​Organization vs. Public Endpoints

​Authentication

​Best Practices

​Related