# Platform MCP Server

> Source: https://truto.one/docs/guides/assistant/platform-mcp-server/

The Truto **Platform MCP server** exposes a small, fixed set of meta-tools for discovering and calling the Truto **platform API**. It is scoped to your workspace — not per-integration proxy tools.

Use it when you want an external AI assistant (Cursor, Claude Desktop, Claude Code, ChatGPT, and so on) to list integrations, inspect connected accounts, run sync jobs, or perform other platform operations on your behalf.

You can find your workspace MCP endpoint on the **Settings → Assistant** page under **Platform MCP Server**.

## Endpoint

The Platform MCP server is a JSON-RPC endpoint on the Truto API:

```
https://api.truto.one/platform/mcp
```

Replace the host if your team uses a different API base URL (for example, a dedicated deployment). The path is always `/platform/mcp`.

## Authentication

Every request must include a Truto **API token** as a Bearer credential:

```
Authorization: Bearer <your_api_token>
```

API tokens have the same access as your Truto user account. Create and manage them in the Truto app under **Settings → API Tokens**. See [Creating API tokens](/docs/guides/api-tokens/creating-api-tokens) for step-by-step instructions.

Integrated-account tokens cannot access the Platform MCP server — use a team API token instead.

## Exposed tools

The server advertises four tools via `tools/list`:

| Tool | Purpose |
| --- | --- |
| `list_api_operations` | Discover REST operations from the Truto OpenAPI catalog (filter by tag, keyword, or path prefix). |
| `describe_api_operation` | Get parameters and request-body schema for a specific operation (`method` + `path`). |
| `call_platform_api` | Execute a platform API call as the authenticated user. Use `fields` or `jsonata` on the request to shape large list responses. |
| `get_capabilities` | Show proxy and unified API surfaces for an integration slug/ID or integrated-account UUID. |

The in-app assistant also exposes `read_platform_resource` and `query_tool_result`. Those tools are **not** available on the Platform MCP server.

The server also supports standard MCP resources and a `platform-assistant` prompt for operator context.

## Client setup

Pick your client and add the config. Substitute your API token and API base URL.

Store tokens in environment variables or your client's secret handling — do not commit API tokens to version control.

### Cursor

Cursor v0.48.0+ connects to **unauthenticated** remote MCP servers natively via a `url` field. The Platform MCP server requires a Bearer token on every request, so use the `mcp-remote` bridge (same transport Claude Desktop uses).

Add to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally, or open **Cursor Settings → Tools & MCP → New MCP Server** to create the file:

```json
{
  "mcpServers": {
    "truto": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.truto.one/platform/mcp",
        "--header",
        "Authorization:${TRUTO_AUTH_HEADER}"
      ],
      "env": {
        "TRUTO_AUTH_HEADER": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

Use `Authorization:${TRUTO_AUTH_HEADER}` with no spaces around `:` — Cursor on Windows mangles spaces inside `args` when invoking `npx`. Put the full `Bearer …` value in `env` instead of splitting it across the argument.

After saving:

1. Restart Cursor (or reload the window).
2. Open **Customize** in the sidebar and confirm **truto** is enabled under MCP servers.
3. If the server stays disconnected, open **Output → MCP Logs** (`Cmd+Shift+U` on macOS) and check for auth or connection errors.

### Claude Desktop

Claude Desktop connects to remote MCP servers through an `npx` bridge. Add this to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "truto": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.truto.one/platform/mcp",
        "--header",
        "Authorization:${TRUTO_AUTH_HEADER}"
      ],
      "env": {
        "TRUTO_AUTH_HEADER": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

Fully quit and reopen Claude Desktop after saving.

### Claude Code

```bash
claude mcp add --transport http truto https://api.truto.one/platform/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

Add `--scope user` to make it available across all projects.

### ChatGPT

ChatGPT connects to remote MCP servers over HTTPS (SSE or Streamable HTTP). Enable **Developer mode**, create an app pointing at your Platform MCP endpoint, then enable the app per chat before using it.

**Plan requirements:** Developer Mode and custom MCP apps are available on ChatGPT Plus, Pro, Business, Enterprise, and Education plans. Business and Enterprise workspaces get full MCP support including write actions. Plus and Pro users can connect read-only custom MCP servers in Developer Mode. See [Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) and the [Developer mode guide](https://platform.openai.com/docs/guides/developer-mode) for current plan details.

**Authentication note:** The Platform MCP server requires `Authorization: Bearer <token>` on every request, including `initialize` and `tools/list`. OpenAI documents OAuth, No Authentication, and Mixed Authentication for custom MCP apps — not static Bearer tokens in the ChatGPT web UI. If your **Create app** screen includes an API key or Bearer token field, paste your Truto API token there. If it only offers OAuth, use Cursor, Claude Desktop, or Claude Code instead, or call the server through the [OpenAI Responses API MCP tool](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) (see below).

**Enable Developer Mode**

- **Individual users:** **Settings → Apps → Advanced settings** → turn on **Developer mode**.
- **Business admins:** enable Developer Mode under [workspace settings](https://chatgpt.com/admin/ca) (**Workspace Settings → Permissions & Roles → Connected Data → Developer mode**), then turn it on for your account under **Settings → Apps → Advanced settings**.
- **Enterprise/Edu:** workspace admins enable Developer Mode via RBAC; authorized members toggle it under **Settings → Apps → Advanced settings**.

**Create the app**

1. With Developer Mode on, go to **Settings → Apps → Create** (admins can also use **Workspace settings → Apps → Create**).
2. Set the MCP server URL to `https://api.truto.one/platform/mcp` (or your team's API base URL with path `/platform/mcp`).
3. Pick the authentication option that matches what the UI offers and what the server requires (see authentication note above).
4. Click **Scan Tools**, wait for the scan to finish, then click **Create**.

The app appears as a draft under **Workspace settings → Apps → Drafts**. Admins publish it for the workspace; until then, you can test it from your own **Settings → Apps** list (marked **Dev**).

**Use the app in a chat**

A saved app is not active until you enable it in the conversation:

1. Start a new chat.
2. Click **+** in the composer → **More** → **Developer Mode** → **Add sources**.
3. Enable your Truto app, then ask a question that should call platform tools (for example, "List my connected accounts").

**OpenAI Responses API (Bearer token)**

If the ChatGPT app UI does not accept a static token, pass your Truto API token in the MCP tool's `authorization` field when calling the [Responses API](https://developers.openai.com/api/docs/guides/tools-connectors-mcp):

```bash
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "tools": [{
      "type": "mcp",
      "server_label": "truto",
      "server_url": "https://api.truto.one/platform/mcp",
      "authorization": "Bearer YOUR_TRUTO_API_TOKEN",
      "require_approval": "never"
    }],
    "input": "List my integrated accounts"
  }'
```

Send the Truto token on every Responses API request — the API does not store the `authorization` value between calls.

Write actions through ChatGPT still require confirmation in the chat UI when using Developer Mode apps. Over Platform MCP, `call_platform_api` returns an `APPROVAL_REQUIRED` error for mutating requests — approve those writes in the **Truto Assistant** chat UI instead.

## Write approvals

Read operations (`GET`, `HEAD`, and operational `POST`s such as `/test`) run immediately through MCP.

**Writes and deletes require approval** when using the in-app Truto Assistant. Over Platform MCP, `call_platform_api` returns an `APPROVAL_REQUIRED` error for:

- `POST`, `PUT`, and `PATCH` requests that mutate platform resources
- All `DELETE` requests and bulk-delete operations
- Calls that touch credentials or other sensitive configuration

Use MCP for discovery and read-only inspection, or approve destructive and write operations in the **Truto Assistant** chat UI instead.

Treat API tokens like passwords — store them in your MCP client's secret handling (environment variables, OS keychain, or your team's secrets manager) rather than committing them to version control.