MCP Servers API

MCP servers expose your connected integrations as tools that AI agents can discover and invoke via the Model Context Protocol. Each server bundles one or more pieces and generates tool definitions automatically.

Weavz MCP servers support two modes: TOOLS mode (one tool per piece action) and CODE mode (three meta-tools for context-efficient usage).

List MCP Servers

Retrieve all MCP servers for the authenticated organization.

GET /api/v1/mcp/servers

Example request

curl https://your-api.example.com/api/v1/mcp/servers \
  -H "Authorization: Bearer wvz_your_api_key"

Example response

{
  "data": [
    {
      "id": "srv_abc123",
      "displayName": "Product Tools",
      "pieces": ["slack", "github", "linear"],
      "mode": "TOOLS",
      "status": "ACTIVE",
      "projectId": "proj_xyz",
      "token": "mcp_token_abc123...",
      "createdAt": "2025-01-20T08:00:00Z",
      "updatedAt": "2025-01-20T08:00:00Z"
    }
  ]
}

Create MCP Server

Create a new MCP server with the specified pieces and mode.

POST /api/v1/mcp/servers

Request body

Example request

curl -X POST https://your-api.example.com/api/v1/mcp/servers \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Engineering Tools",
    "pieces": ["github", "linear", "slack"],
    "mode": "TOOLS"
  }'

Example response

{
  "id": "srv_def456",
  "displayName": "Engineering Tools",
  "pieces": ["github", "linear", "slack"],
  "mode": "TOOLS",
  "status": "ACTIVE",
  "projectId": null,
  "token": "mcp_a1b2c3d4e5f6...",
  "createdAt": "2025-01-20T09:00:00Z",
  "updatedAt": "2025-01-20T09:00:00Z"
}

The token field is the MCP bearer token. Store it securely — it is only returned in create and get responses.

Get MCP Server

Retrieve a single MCP server by ID, including its token.

GET /api/v1/mcp/servers/:id

Example request

curl https://your-api.example.com/api/v1/mcp/servers/srv_def456 \
  -H "Authorization: Bearer wvz_your_api_key"

Update MCP Server

Update an existing MCP server. You can change the display name, pieces, mode, or status.

PATCH /api/v1/mcp/servers/:id

Request body

Example: Add a piece and switch to CODE mode

curl -X PATCH https://your-api.example.com/api/v1/mcp/servers/srv_def456 \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pieces": ["github", "linear", "slack", "notion"],
    "mode": "CODE"
  }'

Delete MCP Server

Permanently delete an MCP server. Any connected MCP clients will lose access immediately.

DELETE /api/v1/mcp/servers/:id

Example request

curl -X DELETE https://your-api.example.com/api/v1/mcp/servers/srv_def456 \
  -H "Authorization: Bearer wvz_your_api_key"

MCP Protocol Endpoint

Each MCP server exposes a protocol endpoint that MCP clients connect to using Server-Sent Events (SSE) transport.

GET /mcp/:serverId

This endpoint requires the MCP bearer token in the Authorization header:

curl https://your-api.example.com/mcp/srv_def456 \
  -H "Authorization: Bearer mcp_a1b2c3d4e5f6..." \
  -H "Accept: text/event-stream"

Note that the MCP endpoint path is /mcp/:serverId, not under /api/v1/. This is a streaming endpoint, not a standard REST endpoint.

TOOLS Mode vs CODE Mode

Weavz MCP servers support two modes that determine how tools are exposed to AI agents.

TOOLS mode

• Generates one MCP tool per piece action (e.g., slack__send_message, github__create_issue).
• Also generates helper tools for dropdown properties (e.g., slack__list_channels) so agents can discover valid values.
• Best for servers with a small number of pieces where full tool discovery is desirable.
• Higher context usage — each tool definition is included in the agent's context window.

CODE mode

• Exposes exactly three meta-tools: weavz_search, weavz_read_api, and weavz_execute.
• weavz_search — search available pieces, actions, and triggers by keyword.
• weavz_read_api — read the full schema for a specific action or trigger.
• weavz_execute — execute an action with provided parameters, or run arbitrary JavaScript in a sandbox.
• 80-98% context reduction compared to TOOLS mode. Ideal for servers with many pieces.

When to use each mode