MCP tools reference

Every tool exposed by Cocobox's MCP server, with arguments, return shapes, and examples.

The Cocobox MCP server (POST /v1/mcp) exposes the tools below to any MCP client. Tools run server-side at the API key’s permissions.

For protocol details, transport, and session lifecycle, see API → MCP.

---

sql_list_connections

List the database connections this API key has access to.

Arguments: none.

Returns:

{
  "connections": [
    { "id": 42, "name": "prod-readonly", "dialect": "postgres", "role": "read" },
    { "id": 17, "name": "staging", "dialect": "mysql", "role": "edit" }
  ]
}

---

sql_list_tables

List tables in a connection’s default database (or a specified schema).

Arguments:

Name	Type	Required	Notes
connection_id	number	✅
schema	string	❌	Defaults to the connection’s default schema.

Returns:

{
  "tables": [
    { "schema": "public", "name": "users", "kind": "table", "rows_estimate": 12483 },
    { "schema": "public", "name": "orders", "kind": "table", "rows_estimate": 88291 }
  ]
}

---

sql_describe

Describe a table or view.

Arguments:

Name	Type	Required
connection_id	number	✅
name	string	✅
schema	string	❌

Returns:

{
  "schema": "public",
  "name": "users",
  "columns": [
    { "name": "id", "type": "int8", "nullable": false, "default": "nextval(…)", "pk": true },
    { "name": "email", "type": "text", "nullable": false, "unique": true },
    { "name": "created_at", "type": "timestamptz", "nullable": false, "default": "now()" }
  ],
  "indexes": [ { "name": "users_email_key", "columns": ["email"], "unique": true } ],
  "foreign_keys": []
}

---

sql_run

Execute a SQL statement and return the result.

Arguments:

Name	Type	Required	Notes
connection_id	number	✅
statement	string	✅	A single SQL statement.
params	array	❌	Positional parameter bindings.
max_rows	number	❌	Default 1000. Cap depends on plan.
timeout_ms	number	❌	Default 30000.

Returns (read):

{
  "kind": "rows",
  "columns": [ { "name": "email" }, { "name": "n_orders" } ],
  "rows": [
    { "email": "ada@example.com", "n_orders": 12 }
  ],
  "row_count": 1,
  "duration_ms": 81
}

Returns (write/DDL):

{ "kind": "affected", "affected_rows": 3, "duration_ms": 22 }

Errors: Cocobox’s SQL gate rejects writes for read-role keys before the DB is touched (403 sql_gate_blocked).

---

sql_explain

Get the engine’s EXPLAIN for a statement.

Arguments:

Name	Type	Required	Notes
connection_id	number	✅
statement	string	✅
analyze	boolean	❌	Pass true for EXPLAIN ANALYZE (Postgres) / EXPLAIN ANALYZE FORMAT=TREE (MySQL 8).

Returns: { "plan": <engine-specific JSON> }.

---

sql_history

Recent statements run on a connection by this API key, for context-building in agents.

Arguments:

Name	Type	Required
connection_id	number	✅
limit	number	❌ (default 20, max 100)

Returns:

{
  "items": [
    {
      "ts": "2026-05-01T12:31:18Z",
      "statement": "SELECT count(*) FROM users",
      "duration_ms": 12,
      "kind": "rows",
      "row_count": 1
    }
  ]
}

---

Tool availability matrix

Tool	Required scope	Read-only?
sql_list_connections	any	yes
sql_list_tables	read on the connection	yes
sql_describe	read on the connection	yes
sql_run (SELECT)	read on the connection	yes
sql_run (write/DDL)	edit on the connection	no
sql_explain	read on the connection	yes
sql_history	read on the connection	yes