Agent Tools

Connecting a tool to an agent is what lets the model call it. The tool must already exist in the workspace catalog ; these endpoints only manage the relationship.

The same tool can be connected to several agents at once, and connecting or disconnecting never modifies the tool or the MCP server / API behind it.

There are two ways to take a tool away from an agent:

Deactivating (PATCH with status: "inactive") keeps the connection but the model stops seeing it. Reversible with a single PATCH.
Disconnecting (DELETE) removes the relationship. Undoing it requires a fresh POST.

At runtime the agent only receives tools whose connection is active. Deactivating is what you want for switching a tool off temporarily.

List Agent Tools

GET https://api.platica.mx/v1/agents/{agentId}/tools

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Agent identifier	✓

Response

{
  "count": 2,
  "tools": [
    {
      "registrationId": "pQ7xLm2NvKdR",
      "toolId": "8fK2mQpLxT4vNbRc",
      "name": "mcp_create_issue_a1b2c3",
      "description": "Create a new issue in Linear",
      "kind": "mcp",
      "status": "active",
      "toolExists": true,
      "registeredAt": "2026-07-14T18:05:22.881Z"
    },
    {
      "registrationId": "Wc4TnB9yHsEz",
      "toolId": "RuzoaswTBBrhutHyKYZn",
      "name": "api_order_lookup",
      "description": "Look up an order status by its reference number.",
      "kind": "api",
      "status": "inactive",
      "toolExists": true,
      "registeredAt": "2026-07-12T09:20:07.554Z"
    }
  ]
}

Field	Type	Description
`registrationId`	string	Internal connection identifier. Informational — every operation uses `toolId`.
`toolId`	string \| null	Catalog tool the connection points at.
`name`, `description`, `kind`	string \| null	Read from the catalog. `null` if the tool no longer exists.
`status`	string	`active` or `inactive`.
`toolExists`	boolean	`false` when the catalog tool was deleted and the connection was left orphaned.
`registeredAt`	string \| null	ISO 8601.

Advertencia

An entry with toolExists: false means the tool it pointed at was removed from the workspace and the connection was orphaned. It does not affect the agent, but you can clean it up with DELETE /v1/agents/{agentId}/tools/{toolId}.

List Connectable Tools

Returns the full workspace catalog, flagging which tools are already connected to this agent. This is how you build a picker without creating duplicate connections.

GET https://api.platica.mx/v1/agents/{agentId}/tools/available

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Agent identifier	✓

Query parameters

Parameter	Type	Description	Required
`kind`	string	Filter by origin: `mcp`, `api`, `integration` or `legacy`	—
`workspace`	string	Required for multi-workspace API keys	—

Response

Each item has the same fields as the catalog plus two:

{
  "count": 1,
  "tools": [
    {
      "id": "8fK2mQpLxT4vNbRc",
      "name": "mcp_create_issue_a1b2c3",
      "description": "Create a new issue in Linear",
      "kind": "mcp",
      "parameters": { "type": "object", "properties": {} },
      "status": "active",
      "mcpId": "QZPHpckDPC58JIVLQA3Z",
      "mcpToolName": "create_issue",
      "mcpName": "Linear",
      "mcpStatus": "connected",
      "integrationId": null,
      "integrationName": null,
      "integrationStatus": null,
      "installationId": null,
      "providerId": null,
      "providerToolName": null,
      "createdAt": "2026-07-14T18:02:11.410Z",
      "updatedAt": "2026-07-14T18:02:11.410Z",
      "isConnected": true,
      "connectionStatus": "active"
    }
  ]
}

Field	Type	Description
`isConnected`	boolean	Whether the agent already has this tool connected.
`connectionStatus`	string \| null	`active`, `inactive`, or `null` when not connected.

Connect Tool

POST https://api.platica.mx/v1/agents/{agentId}/tools

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Agent identifier	✓

Request Body

{
  "toolId": "8fK2mQpLxT4vNbRc",
  "status": "active"
}

Parameter	Type	Description	Required	Default
`toolId`	string	Catalog tool identifier	✓	—
`status`	string	`"active"` or `"inactive"`. With `"inactive"` it stays connected but the model does not see it	—	`"active"`

Response

{
  "status": "success",
  "message": "Tool connected successfully",
  "data": {
    "connection": {
      "registrationId": "pQ7xLm2NvKdR",
      "toolId": "8fK2mQpLxT4vNbRc",
      "name": "mcp_create_issue_a1b2c3",
      "description": "Create a new issue in Linear",
      "kind": "mcp",
      "status": "active",
      "toolExists": true,
      "registeredAt": "2026-07-14T18:05:22.881Z"
    }
  }
}

Errors

Status	Cause
`404`	The agent does not exist, or the tool is not in the workspace catalog
`409`	The tool is already connected to this agent — use `PATCH` to change its state

Activate or Deactivate Tool

PATCH https://api.platica.mx/v1/agents/{agentId}/tools/{toolId}

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Agent identifier	✓
`toolId`	string	Catalog tool identifier	✓

Request Body

{
  "status": "inactive"
}

Parameter	Type	Description	Required
`status`	string	`"active"` or `"inactive"`	✓

Response

{
  "status": "success",
  "message": "Tool status updated to inactive",
  "data": {
    "connection": {
      "registrationId": "pQ7xLm2NvKdR",
      "toolId": "8fK2mQpLxT4vNbRc",
      "name": "mcp_create_issue_a1b2c3",
      "description": "Create a new issue in Linear",
      "kind": "mcp",
      "status": "inactive",
      "toolExists": true,
      "registeredAt": "2026-07-14T18:05:22.881Z"
    }
  }
}

Activating a tool that was not connected connects it, so this endpoint is idempotent: asking for status: "active" always leaves the agent with the tool active, whether it was connected before or not.

Errors

Status	Cause
`404`	The agent or the tool does not exist, or `"inactive"` was requested on a tool that is not connected

Disconnect Tool

Removes the connection. The tool stays in the catalog and other agents using it are unaffected.

DELETE https://api.platica.mx/v1/agents/{agentId}/tools/{toolId}

URL parameters

Parameter	Type	Description	Required
`agentId`	string	Agent identifier	✓
`toolId`	string	Catalog tool identifier	✓

Response

{
  "status": "success",
  "message": "Tool disconnected successfully",
  "data": {
    "toolId": "8fK2mQpLxT4vNbRc",
    "removedRegistrations": 1
  }
}

removedRegistrations is normally 1. It can be higher if the agent had duplicate connections to the same tool, in which case all of them are removed.

Errors

Status	Cause
`404`	The agent does not exist, or the tool is not connected

Previous Workspace Catalog Next MCP Servers