Tools

A tool is a function an agent can call mid-conversation: look up an order, open a ticket, book an appointment. Platica manages them in three layers, and understanding those layers is all you need to use these endpoints:

The connectors create tools. There are two: MCP servers and custom APIs .
The workspace catalog is the list of everything that exists and can be used. It lives at /v1/tools .
The agent connection is what lets a specific agent call it. It lives at /v1/agents/{agentId}/tools .

The three are deliberately separate steps: installing a tool in the workspace does not give it to any agent, and disconnecting it from an agent does not remove it from the workspace. A full flow looks like this:

POST /v1/tools/mcp                       → connect the server and install its tools
GET  /v1/tools                           → read the catalog toolIds
POST /v1/agents/{agentId}/tools          → give it to the agent

Workspace catalog

Method	Endpoint	Description
`GET`	`/v1/tools`	List the catalog (`?kind=&mcpId=&integrationId=`)
`GET`	`/v1/tools/{toolId}`	Get one tool with its full schema

Agent tools

Method	Endpoint	Description
`GET`	`/v1/agents/{agentId}/tools`	List connected tools
`GET`	`/v1/agents/{agentId}/tools/available`	List the catalog flagged with what is already connected
`POST`	`/v1/agents/{agentId}/tools`	Connect a tool
`PATCH`	`/v1/agents/{agentId}/tools/{toolId}`	Activate or deactivate the connection
`DELETE`	`/v1/agents/{agentId}/tools/{toolId}`	Disconnect

MCP servers

Method	Endpoint	Description
`POST`	`/v1/tools/mcp/preview`	See what a server exposes, without saving anything
`GET`	`/v1/tools/mcp`	List connected servers
`POST`	`/v1/tools/mcp`	Connect a server and install its tools
`GET`	`/v1/tools/mcp/{mcpId}`	Get a server with its tools
`POST`	`/v1/tools/mcp/{mcpId}/oauth/start`	Start or restart OAuth authorization
`POST`	`/v1/tools/mcp/{mcpId}/refresh`	Re-discover tools and update schemas
`POST`	`/v1/tools/mcp/{mcpId}/tools/sync`	Set which tools stay installed
`DELETE`	`/v1/tools/mcp/{mcpId}`	Disconnect the server and remove its tools

Custom APIs

Method	Endpoint	Description
`GET`	`/v1/tools/apis`	List configured APIs
`POST`	`/v1/tools/apis`	Create one (starts as a draft)
`GET`	`/v1/tools/apis/{integrationId}`	Get the full definition
`PATCH`	`/v1/tools/apis/{integrationId}`	Partial update
`POST`	`/v1/tools/apis/{integrationId}/test`	Test it with sample values
`POST`	`/v1/tools/apis/{integrationId}/enable`	Publish it to the catalog
`POST`	`/v1/tools/apis/{integrationId}/pause`	Withdraw it from the catalog, keeping the config
`DELETE`	`/v1/tools/apis/{integrationId}`	Delete it

Tool kinds

The kind field says where a catalog tool came from:

`kind`	Origin	Managed at
`mcp`	Installed from an MCP server	`/v1/tools/mcp`
`api`	An enabled custom API	`/v1/tools/apis`
`integration`	A first-party app installed from the dashboard	Platica dashboard
`legacy`	Classic-editor HTTP tool (`request_*` name)	Platica dashboard

Every kind connects to an agent the same way, through the same endpoints. The connectors only differ at creation time.

States

There are two independent states, and they are easy to confuse:

The connection state (active / inactive) decides whether the agent sees the tool. Only active connections are passed to the model at runtime. Deactivating is reversible and keeps the connection.
The source state — an MCP server's status, or a custom API's draft / enabled / paused — decides whether the tool exists in the catalog at all. An API in draft or paused has no catalog entry, so it cannot be connected to anyone.

Consejo

API keys with access to multiple workspaces must include ?workspace={workspaceId} on every operation under /v1/tools/... and /v1/agents/{agentId}/tools/....

Permissions

Endpoints under /v1/tools belong to the workspace integrations module; those under /v1/agents/{agentId}/tools belong to agents. API keys have full workspace access, so this distinction only matters when a Platica agent calls the API with delegated permissions.

Previous Knowledge Base Next Workspace Catalog