MCP Servers

Create and manage Model Context Protocol (MCP) servers.

MCP Servers

MCP servers expose integration actions as tools for AI agents via the Model Context Protocol. Each server has its own bearer token and endpoint URL that can be used with any MCP-compatible client.

Servers operate in two modes:

TOOLS — each integration action is exposed as an individual tool
CODE — meta-tools let AI agents write code to orchestrate multiple actions

List MCP Servers

GET/api/v1/mcp/servers

List all MCP servers in your organization.

Response

json

{
  "servers": [
    {
      "id": "abc123def456",
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Sales Tools",
      "description": "CRM and email integrations",
      "mode": "TOOLS",
      "endUserId": null,
      "createdBy": "user123",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "mcpEndpoint": "https://api.weavz.io/mcp/srv_abc123def456"
    }
  ],
  "total": 1
}

Example

bash

curl https://api.weavz.io/api/v1/mcp/servers \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { servers } = await client.mcpServers.list()

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.mcp_servers.list()
servers = result["servers"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

import httpx
 
res = httpx.get(
    "https://api.weavz.io/api/v1/mcp/servers",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Create MCP Server

POST/api/v1/mcp/servers

Create a new MCP server. The response includes a bearerToken that MCP clients use to authenticate — this is only shown once.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Server name
`description`	string	No	Server description
`workspaceId`	string (uuid)	Yes	Associate with a workspace
`mode`	string	No	Server mode: `TOOLS` or `CODE` (default: `TOOLS`)
`endUserId`	string	No	Scope the server to an end user. Connections resolve to this user's accounts.

Response (201)

json

{
  "server": {
    "id": "abc123def456",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Sales Tools",
    "description": "CRM and email integrations",
    "mode": "TOOLS",
    "endUserId": null,
    "createdBy": "user123",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z",
    "mcpEndpoint": "https://api.weavz.io/mcp/srv_abc123def456"
  },
  "bearerToken": "mcp_abc123...",
  "mcpEndpoint": "https://api.weavz.io/mcp/srv_abc123def456"
}

Example

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Tools",
    "description": "CRM and email integrations",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "mode": "TOOLS"
  }'

typescript

const { server, bearerToken, mcpEndpoint } = await client.mcpServers.create({
  name: 'Sales Tools',
  description: 'CRM and email integrations',
  workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  mode: 'TOOLS',
})

python

result = client.mcp_servers.create(
    name="Sales Tools",
    description="CRM and email integrations",
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    mode="TOOLS",
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Sales Tools',
    description: 'CRM and email integrations',
    workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    mode: 'TOOLS',
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "name": "Sales Tools",
        "description": "CRM and email integrations",
        "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "mode": "TOOLS",
    },
)
data = res.json()

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing server name
`403`	`QUOTA_EXCEEDED`	MCP server limit reached

Get MCP Server

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

Get server details including its configured tools.

Path Parameters

Field	Type	Description
`id`	string	Server ID

Response

json

{
  "server": {
    "id": "abc123def456",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Sales Tools",
    "mode": "TOOLS",
    "endUserId": null,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z",
    "mcpEndpoint": "https://api.weavz.io/mcp/srv_abc123def456"
  },
  "tools": [
    {
      "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "mcpServerId": "abc123def456",
      "integrationName": "slack",
      "integrationAlias": "slack",
      "actionName": "send_channel_message",
      "toolType": "ACTION",
      "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "displayName": null,
      "description": null,
      "inputDefaults": null,
      "sortOrder": 0
    }
  ]
}

Example

bash

curl https://api.weavz.io/api/v1/mcp/servers/abc123def456 \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

const { server, tools } = await client.mcpServers.get('abc123def456')

python

result = client.mcp_servers.get("abc123def456")

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

res = httpx.get(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`404`	`NOT_FOUND`	MCP server not found

Update MCP Server

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

Update server properties.

Path Parameters

Field	Type	Description
`id`	string	Server ID

Request Body

Field	Type	Required	Description
`name`	string	No	Server name
`description`	string	No	Server description
`mode`	string	No	`TOOLS` or `CODE`
`endUserId`	string \| null	No	Scope to an end user, or `null` to remove

Response

json

{
  "server": {
    "id": "abc123def456",
    "name": "Updated Name",
    "mode": "CODE",
    "updatedAt": "2025-01-16T14:00:00.000Z"
  }
}

Example

bash

curl -X PATCH https://api.weavz.io/api/v1/mcp/servers/abc123def456 \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "mode": "CODE"}'

typescript

const { server } = await client.mcpServers.update('abc123def456', {
  name: 'Updated Name',
  mode: 'CODE',
})

python

result = client.mcp_servers.update("abc123def456", name="Updated Name", mode="CODE")

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Updated Name', mode: 'CODE' }),
})
const data = await res.json()

python

res = httpx.patch(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"name": "Updated Name", "mode": "CODE"},
)
data = res.json()

Errors

Status	Code	Description
`404`	`NOT_FOUND`	MCP server not found

Delete MCP Server

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

Delete an MCP server and all its tools.

Path Parameters

Field	Type	Description
`id`	string	Server ID

Response

json

{
  "deleted": true,
  "id": "abc123def456"
}

Example

bash

curl -X DELETE https://api.weavz.io/api/v1/mcp/servers/abc123def456 \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

await client.mcpServers.delete('abc123def456')

python

client.mcp_servers.delete("abc123def456")

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

res = httpx.delete(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`404`	`NOT_FOUND`	MCP server not found

Regenerate Token

POST/api/v1/mcp/servers/:id/regenerate-token

Regenerate the MCP bearer token. The old token is immediately invalidated.

Path Parameters

Field	Type	Description
`id`	string	Server ID

Response

json

{
  "bearerToken": "mcp_new_token_here...",
  "mcpEndpoint": "https://api.weavz.io/mcp/srv_abc123def456"
}

Example

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers/abc123def456/regenerate-token \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

const { bearerToken, mcpEndpoint } = await client.mcpServers.regenerateToken('abc123def456')

python

result = client.mcp_servers.regenerate_token("abc123def456")

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456/regenerate-token', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456/regenerate-token",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`404`	`NOT_FOUND`	MCP server not found

Add Tool

POST/api/v1/mcp/servers/:id/tools

Add an integration action as a tool to the server.

Path Parameters

Field	Type	Description
`id`	string	Server ID

Request Body

Field	Type	Required	Description
`integrationName`	string	Yes	Integration name
`actionName`	string	Yes	Action name
`integrationAlias`	string	No	Alias for the integration (defaults to `integrationName`). Must match `^[a-z][a-z0-9_-]*$`, max 64 chars
`toolType`	string	No	`ACTION` or `TRIGGER` (default: `ACTION`)
`connectionId`	string (uuid)	No	Connection to use for this tool
`displayName`	string	No	Custom display name
`description`	string	No	Custom description
`inputDefaults`	object	No	Default input values
`partialIds`	string[]	No	Partial IDs to apply to this tool
`sortOrder`	number	No	Sort position (default: 0)

Integration aliases allow the same integration to appear multiple times on a server under different names (e.g., slack_bot and slack_user), each with its own connection.

Response (201)

json

{
  "tool": {
    "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "mcpServerId": "abc123def456",
    "integrationName": "slack",
    "integrationAlias": "slack_bot",
    "actionName": "send_channel_message",
    "toolType": "ACTION",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "sortOrder": 0
  }
}

Example

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "integrationAlias": "slack_bot",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab"
  }'

typescript

const { tool } = await client.mcpServers.addTool('abc123def456', {
  integrationName: 'slack',
  actionName: 'send_channel_message',
  integrationAlias: 'slack_bot',
  connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
})

python

result = client.mcp_servers.add_tool(
    "abc123def456",
    integration_name="slack",
    action_name="send_channel_message",
    integration_alias="slack_bot",
    connection_id="c1d2e3f4-5678-90ab-cdef-1234567890ab",
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    actionName: 'send_channel_message',
    integrationAlias: 'slack_bot',
    connectionId: 'c1d2e3f4-5678-90ab-cdef-1234567890ab',
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "integrationAlias": "slack_bot",
        "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    },
)
data = res.json()

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing required fields or invalid alias format
`404`	`NOT_FOUND`	MCP server not found
`409`	`DUPLICATE`	Tool already exists on this server
`409`	`ALIAS_CONFLICT`	Alias is already mapped to a different integration

Update Tool

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

Update a tool's configuration.

Path Parameters

Field	Type	Description
`id`	string	Server ID
`toolId`	string (uuid)	Tool ID

Request Body

Field	Type	Required	Description
`displayName`	string	No	Custom display name
`description`	string	No	Custom description
`inputDefaults`	object	No	Default input values
`connectionId`	string (uuid)	No	Connection to use
`sortOrder`	number	No	Sort position
`integrationAlias`	string	No	Updated alias

Response

json

{
  "tool": {
    "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "integrationAlias": "slack_bot",
    "displayName": "Send Bot Message",
    "sortOrder": 1
  }
}

Example

bash

curl -X PATCH https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools/f1e2d3c4-b5a6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Send Bot Message", "sortOrder": 1}'

typescript

const { tool } = await client.mcpServers.updateTool('abc123def456', 'f1e2d3c4-b5a6-7890-abcd-ef1234567890', {
  displayName: 'Send Bot Message',
  sortOrder: 1,
})

python

result = client.mcp_servers.update_tool(
    "abc123def456",
    "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    display_name="Send Bot Message",
    sort_order=1,
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools/f1e2d3c4-b5a6-7890-abcd-ef1234567890', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ displayName: 'Send Bot Message', sortOrder: 1 }),
})
const data = await res.json()

python

res = httpx.patch(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools/f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"displayName": "Send Bot Message", "sortOrder": 1},
)
data = res.json()

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Invalid fields
`404`	`NOT_FOUND`	Server or tool not found

Remove Tool

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

Remove a tool from the server.

Path Parameters

Field	Type	Description
`id`	string	Server ID
`toolId`	string (uuid)	Tool ID

Response

json

{
  "deleted": true,
  "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
}

Example

bash

curl -X DELETE https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools/f1e2d3c4-b5a6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

await client.mcpServers.deleteTool('abc123def456', 'f1e2d3c4-b5a6-7890-abcd-ef1234567890')

python

client.mcp_servers.delete_tool("abc123def456", "f1e2d3c4-b5a6-7890-abcd-ef1234567890")

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools/f1e2d3c4-b5a6-7890-abcd-ef1234567890', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

res = httpx.delete(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456/tools/f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`404`	`NOT_FOUND`	Server or tool not found

Execute Code

POST/api/v1/mcp/servers/:id/execute-code

Execute code against a CODE mode server. Used for testing code-mode integrations.

Path Parameters

Field	Type	Description
`id`	string	Server ID

Request Body

Field	Type	Required	Description
`code`	string	Yes	JavaScript code to execute

Response

json

{
  "content": [
    {
      "type": "text",
      "text": "Execution result..."
    }
  ],
  "isError": false
}

Example

bash

curl -X POST https://api.weavz.io/api/v1/mcp/servers/abc123def456/execute-code \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"code": "const result = await weavz.slack.send_channel_message({ channel: \"C123\", text: \"Hello\" }); return result;"}'

typescript

const { content, isError } = await client.mcpServers.executeCode(
  'abc123def456',
  'const result = await weavz.slack.send_channel_message({ channel: "C123", text: "Hello" }); return result;',
)

python

result = client.mcp_servers.execute_code(
    "abc123def456",
    'const result = await weavz.slack.send_channel_message({ channel: "C123", text: "Hello" }); return result;',
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456/execute-code', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'const result = await weavz.slack.send_channel_message({ channel: "C123", text: "Hello" }); return result;',
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456/execute-code",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "code": 'const result = await weavz.slack.send_channel_message({ channel: "C123", text: "Hello" }); return result;',
    },
)
data = res.json()

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing code
`403`	`QUOTA_EXCEEDED`	Sandbox quota exceeded
`404`	`NOT_FOUND`	MCP server not found

Get TypeScript Declarations

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

Get TypeScript declarations for an integration on a CODE mode server. Returns type definitions for the weavz.* API surface.

Path Parameters

Field	Type	Description
`id`	string	Server ID
`integrationOrAlias`	string	Integration name or alias

Response

json

{
  "declarations": "declare namespace weavz {\n  namespace slack {\n    function send_channel_message(input: { channel: string; text: string }): Promise<any>;\n  }\n}"
}

Example

bash

curl https://api.weavz.io/api/v1/mcp/servers/abc123def456/declarations/slack \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

const { declarations } = await client.mcpServers.getDeclarations('abc123def456', 'slack')

python

result = client.mcp_servers.get_declarations("abc123def456", "slack")

typescript

const res = await fetch('https://api.weavz.io/api/v1/mcp/servers/abc123def456/declarations/slack', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

res = httpx.get(
    "https://api.weavz.io/api/v1/mcp/servers/abc123def456/declarations/slack",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`404`	`NOT_FOUND`	Server or integration not found