Weavz

MCP Servers

An MCP server in Weavz exposes a curated set of integrations as tools via the Model Context Protocol. Any MCP-compatible client — Claude Desktop, Cursor, custom AI agents — can connect to a Weavz MCP server and discover, describe, and invoke integration tools without any custom code.

Creating an MCP Server

You can create MCP servers through the dashboard or the REST API. When creating a server, you specify:

  • Name: A human-readable label for the server
  • Mode: Either TOOLS or CODE (see below)
  • Pieces: Which integrations to expose (e.g. slack, github, google-sheets)
  • Project: Optional project scope for connection resolution

Each server gets a unique bearer token (prefixed with mcp_) and an SSE endpoint URL. Clients connect to the SSE endpoint and pass the bearer token in the Authorization header.

# MCP server endpoint format
GET /mcp/servers/{serverId}/sse
Authorization: Bearer mcp_xxxxxxxxxxxxx

TOOLS Mode

In TOOLS mode, each action from the selected pieces becomes a separate MCP tool. The tool name follows the pattern {pieceName}__{actionName} and includes a full JSON Schema describing its input parameters.

For example, if you select the slack piece, the server exposes tools like:

  • slack__send_message — Send a message to a channel
  • slack__create_channel — Create a new Slack channel
  • slack__list_channels — List channels in the workspace
  • slack__add_reaction — Add an emoji reaction to a message

Each tool includes a complete description and input schema, so AI agents can understand what the tool does and what parameters it requires without any additional documentation.

When to Use TOOLS Mode

  • You are exposing a small number of pieces (1–3)
  • The AI client has a large context window
  • You want the agent to see full parameter schemas upfront
  • You prefer simplicity over context efficiency

CODE Mode

In CODE mode, the server exposes exactly three meta-tools instead of one tool per action. This dramatically reduces the context consumed by tool definitions — typically by 80 to 98 percent — making it ideal for servers with many pieces or for AI clients with limited context windows.

The three meta-tools are:

weavz_search

Searches across all available pieces, actions, and triggers. The agent uses this to discover what capabilities are available without loading full schemas.

// Example: Agent asks "What can I do with Slack?"
weavz_search({ query: "slack" })

// Returns a compact list of matching actions and triggers
// with names, descriptions, and piece info — no full schemas

weavz_read_api

Retrieves the full TypeScript declaration for a specific action or trigger. The agent calls this when it has identified an action it wants to use and needs the complete parameter schema.

// Example: Agent wants to know how to send a Slack message
weavz_read_api({ pieceName: "slack", actionName: "send_message" })

// Returns a TypeScript declaration with full type info:
// interface SendMessageInput {
//   channel: string   // Channel ID or name
//   text: string      // Message text (supports markdown)
//   thread_ts?: string // Reply to thread
// }

weavz_execute

Executes an action by running a JavaScript code snippet in a sandboxed environment. The code has access to a weavz global that provides typed methods for each available action.

// Example: Send a Slack message and create a GitHub issue
weavz_execute({
  code: `
    const slackResult = await weavz.slack.send_message({
      channel: "#general",
      text: "Deployment complete!"
    });

    const issue = await weavz.github.create_issue({
      repo: "my-org/my-repo",
      title: "Deployment notification sent",
      body: \`Slack message ts: \${slackResult.ts}\`
    });

    return { slackResult, issue };
  `
})

Learn more about Code Mode for a deep dive into the sandbox architecture, persistent storage, and advanced patterns.

When to Use CODE Mode

  • You are exposing many pieces (4+)
  • Context efficiency matters (smaller models, tight token budgets)
  • The agent needs to chain multiple actions in a single step
  • You want the agent to write composable integration logic

Helper Tools

Many piece actions have DROPDOWN properties — parameters whose valid values must be fetched from the third-party API at runtime (e.g. a list of Slack channels, GitHub repos, or Google Drive folders). In TOOLS mode, Weavz automatically generates helper tools for these properties so AI agents can discover valid values.

Helper tools follow the naming convention {pieceName}__list_{propertyName}s:

// Auto-generated helper tool for Slack channels
slack__list_channels()

// Auto-generated helper tool for GitHub repos
github__list_repos({ org: "my-org" })

// Helper tools for dependent dropdowns include the parent value
google_sheets__list_sheets({ spreadsheetId: "abc123" })

In CODE mode, dropdown discovery is handled through the weavz.$options API instead of separate helper tools. See the Code Mode docs for details.

Authentication

MCP servers use bearer token authentication. The token is generated when the server is created and is prefixed with mcp_ to distinguish it from API keys (wvz_ prefix).

To connect a client, pass the token in the Authorization header:

Authorization: Bearer mcp_xxxxxxxxxxxxx

The bearer token grants access only to the pieces and connections configured for that specific server. It does not grant general API access to the organization.

Transport

Weavz MCP servers use the SSE (Server-Sent Events) transport. The client connects to the SSE endpoint and sends tool invocations as HTTP POST requests. The server streams responses back through the SSE connection.

The SSE transport is supported by all major MCP clients and works through proxies and load balancers without special configuration.

Managing Servers via API

# List MCP servers
GET /api/v1/mcp/servers

# Create a server
POST /api/v1/mcp/servers
{
  "name": "My Server",
  "mode": "TOOLS",
  "pieceNames": ["slack", "github"]
}

# Get server details (includes token)
GET /api/v1/mcp/servers/:id

# Update server configuration
PATCH /api/v1/mcp/servers/:id

# Delete a server
DELETE /api/v1/mcp/servers/:id

Related

  • Code Mode — Deep dive into the three meta-tools and sandbox execution
  • Connections — How credentials are resolved for MCP tool invocations
  • Quick Start — Set up your first MCP server