Skip to content
Chatvia Docs
On this page

API reference

Connectors

Get in touch: Ahmad Mayahi, creator of Chatvia, Spectra and Shakomako

These endpoints manage MCP servers and decide which agents may use them. MCP (Model Context Protocol) is an open standard for offering tools to an AI model. An MCP server is a service that offers such tools, for example "create a ticket" or "search the wiki". MCP connectors explains connectors for people who use the dashboard.

For example, if your company runs its own MCP server for its inventory system, a script can add it to the workspace and attach it to every new agent it creates.

There are two kinds of servers:

  • Custom servers (kind: custom) are your own. You can add and delete them through the API, when they use a bearer token or no sign-in at all.
  • Catalog connectors (kind: catalog), such as GitHub or Slack, are connected in the dashboard under Workspace → Integrations → Connectors, because most sign in with OAuth in a browser. The API can list them and attach them to agents, but not add or delete them.

Read the overview first for the base URL, keys, errors and paging.

The connector object

json
{
  "id": "0199f3e2-6b7c-7d8e-9f0a-1b2c3d4e5f60",
  "kind": "custom",
  "name": "Inventory",
  "slug": "inventory",
  "url": "https://mcp.example.com/inventory",
  "transport": "streamable_http",
  "auth_type": "bearer",
  "has_auth_value": true,
  "has_headers": false,
  "timeout_ms": 60000,
  "is_enabled": true,
  "catalog_tools_count": 6,
  "last_invoked_at": null,
  "invocation_count": 0,
  "created_at": "2026-10-25T10:02:17+00:00"
}
Field Type Meaning
id string The server's id.
kind string custom for your own servers, catalog for a connector from the catalog.
name string The name shown in the dashboard.
slug string or null A short name made from the display name.
url string or null The server's address.
transport string How Chatvia talks to the server: streamable_http or http_sse.
auth_type string none, bearer or header.
has_auth_value boolean Whether a secret is stored. The secret itself is never returned.
has_headers boolean Whether extra headers are set.
timeout_ms integer or null How long Chatvia waits for the server, in milliseconds.
is_enabled boolean Whether the server is on.
catalog_tools_count integer or null How many tools Chatvia found on the server.
last_invoked_at string or null When an agent last called one of its tools.
invocation_count integer How many times agents called its tools.
created_at string When the server was added.

List connectors

Returns the MCP servers of your workspace, custom and catalog, newest first.

text
GET /api/v1/mcps

Who can call it: the owner, or a teammate with Connectors.

bash
curl https://chat.example.com/api/v1/mcps \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [connector, …], "next_cursor": … }. See Pagination.

Add a connector

Adds a custom MCP server and reads its list of tools.

text
POST /api/v1/mcps

Who can call it: the owner, or a teammate with Connectors.

Body field Type Required Notes
name string yes Up to 100 characters.
url string yes The server's address. Must start with https://. Up to 2,048 characters.
auth_strategy string yes token sends a bearer token with every call. none sends nothing.
token string with token The bearer token. Stored encrypted. Up to 4,096 characters.
bash
curl https://chat.example.com/api/v1/mcps \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://mcp.example.com/inventory",
    "auth_strategy": "token",
    "token": "your-mcp-token"
  }'

The answer is 201 Created with { "data": connector }.

Chatvia connects to the server right away to read its tools. When that fails, for example because the address or the token is wrong, the server is not kept and the answer is a 422 on url with the reason.

Good to know:

  • A new server is not attached to any agent yet. See Attach a connector to an agent.
  • Each tool's permission (Always allow, Needs approval or Blocked) is set in the dashboard, on the connector's Tools tab. Read-only tools start as Always allow, others as Needs approval.
  • Tools that need approval are left out of API conversations, because no one can click Approve there.
  • A server that signs in with OAuth must be added in the dashboard.

Get a connector

text
GET /api/v1/mcps/{mcp}

Who can call it: the owner, or a teammate with Connectors.

bash
curl https://chat.example.com/api/v1/mcps/0199f3e2-6b7c-7d8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": connector }.

Delete a connector

Deletes a custom server and removes it from every agent.

text
DELETE /api/v1/mcps/{mcp}

Who can call it: the owner, or a teammate with Connectors.

bash
curl -X DELETE https://chat.example.com/api/v1/mcps/0199f3e2-6b7c-7d8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content. A catalog connector is a 404 here. Disconnect it in the dashboard.

List an agent's connectors

Returns the servers attached to one agent, newest first. This list can also hold built-in capabilities the agent has on, such as Forms.

text
GET /api/v1/agents/{agent}/mcps

Who can call it: anyone with access to the agent.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/mcps \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [connector, …], "next_cursor": … }.

Attach a connector to an agent

Lets the agent use the tools of one of your servers.

text
POST /api/v1/agents/{agent}/mcps

Who can call it: the owner, or a teammate with Manage Connectors.

Body field Type Required Notes
mcp_id string yes The id of one of your servers, custom or catalog. Any other id is a 422.
bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/mcps \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_id": "0199f3e2-6b7c-7d8e-9f0a-1b2c3d4e5f60" }'

The answer is 200 OK with { "data": connector }. Attaching a server the agent already has changes nothing.

Detach a connector from an agent

Stops the agent from using the server. The server stays in your workspace.

text
DELETE /api/v1/agents/{agent}/mcps/{mcp}

Who can call it: the owner, or a teammate with Manage Connectors.

bash
curl -X DELETE https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/mcps/0199f3e2-6b7c-7d8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content.

Search guides, settings and commands.