MCP Quickstart

Triggo ships an embedded Model Context Protocol server at POST /mcp. Point any MCP-native client — Claude Desktop, Claude Code, Cursor, Windsurf, or something you wrote yourself — at that endpoint with a Bearer API key, and the client will immediately discover all 19 Triggo tools. This page walks through the five most common wirings end to end and lists every tool the server registers.

Prerequisites

Before you start you need three things:

1. A Triggo account with at least one workspace. The MCP server is multi-tenant and scopes every call to the workspace that owns the API key.
2. An API key with the scopes the tools you intend to call require. At a minimum, for the "run a published action" flow, the key needs actions:read, actions:run, and runs:read. See API Keys for how to create one.
3. At least one published workflow in the workspace. Unpublished drafts are invisible to the list_actions / run_action tools. See Publishing Workflows as Actions for the publish flow.

Transport and endpoint

The server speaks JSON-RPC over Streamable HTTP. One HTTP POST per MCP message, request and response bodies are JSON-RPC envelopes:

• Endpoint: POST https://api.triggo.dev/mcp
• Auth: Authorization: Bearer trg_... — same key shape that the runtime REST API uses. Both Bearer API keys and OAuth access tokens (from the Better Auth OIDC provider) are accepted.
• Content type: application/json
• Rate limiting: per-key sliding window, tier-aware. A 429 response includes a retry-after header in seconds; every response carries x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset (epoch seconds).

The current deployment instantiates a fresh MCP server per HTTP request, so sessions are stateless as far as the client is concerned: there is no session-id handshake to track, and each POST is complete on its own. If you are embedding the session-aware Streamable HTTP transport from the MCP SDK, it will work — the server simply does not require the session-id flow.

Server identity (returned by the MCP initialize handshake): name triggo-runtime, version 1.0.0, capabilities { tools, resources, prompts }.

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows, and add:

{
  "mcpServers": {
    "triggo-runtime": {
      "url": "https://api.triggo.dev/mcp",
      "headers": {
        "Authorization": "Bearer trg_YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. The Triggo tools appear under the plug icon in the composer. If your Claude Desktop build does not yet support URL-based MCP servers (older releases required a process-based stdio transport), use the mcp-remote bridge instead:

{
  "mcpServers": {
    "triggo-runtime": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.triggo.dev/mcp",
        "--header",
        "Authorization: Bearer trg_YOUR_API_KEY"
      ]
    }
  }
}

mcp-remote terminates the Streamable HTTP transport locally and re-exposes it to Claude Desktop over stdio. Prefer the URL form when supported — it has one fewer moving part.

Claude Code

Add to your project's .claude/settings.json (or the user-level ~/.claude/settings.json for global access):

{
  "mcpServers": {
    "triggo-runtime": {
      "type": "url",
      "url": "https://api.triggo.dev/mcp",
      "headers": {
        "Authorization": "Bearer trg_YOUR_API_KEY"
      }
    }
  }
}

The explicit "type": "url" tells Claude Code to open a Streamable HTTP transport rather than spawning a subprocess. Run claude mcp list from your shell afterwards to confirm Triggo shows up with 19 tools.

Cursor

Open Cursor Settings → Features → Model Context Protocol, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "triggo-runtime": {
      "url": "https://api.triggo.dev/mcp",
      "headers": {
        "Authorization": "Bearer trg_YOUR_API_KEY"
      }
    }
  }
}

Reopen the Cursor chat panel. The tool badge should show triggo-runtime (19).

Generic MCP client

Any HTTP client that can POST JSON with a Bearer header can talk to the endpoint. Here is a minimal tools/list call via curl:

curl -sS https://api.triggo.dev/mcp \
  -H "Authorization: Bearer trg_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

You will get back a JSON-RPC envelope with a result.tools array. From there, the usual MCP message flow applies: initialize to negotiate protocol version, tools/list to enumerate, tools/call to invoke with { "name": "list_actions", "arguments": { "status": "active" } }, and so on. If you are writing an agent in TypeScript or Python, prefer the official @modelcontextprotocol/sdk clients — they handle the envelope framing and capability negotiation for you.

Available tools (19)

Every tool below checks the listed scope before executing. A call that passes auth but lacks the scope returns a JSON-RPC result with isError: true and an explicit FORBIDDEN-style code; it does not reject the entire connection.

That's 19 tools total — 6 Actions, 7 Workflows, 3 Connectors, 3 Builds.

The server also exposes MCP resources and prompts capabilities. Tool discovery is the primary surface; resources and prompts are used by the triggo-runtime server's built-in onboarding text and are safe to ignore for most agent integrations.

Troubleshooting

• 401 Unauthorized — the Bearer token is missing, malformed, expired, or revoked. Recreate the key in Agent Setup and redeploy.
• 403 Forbidden on a specific tool — the key is valid but does not carry the scope the tool requires. Add the scope to the key (or mint a new key) and retry. The scope name appears in the table above.
• No tools visible after connecting — the key validated but has an empty scope list, so every tool's pre-flight scope check fails. Edit the key and add at least actions:read, actions:run, runs:read, connectors:read.
• Connection refused / DNS error — you have the wrong host, or the Triggo instance is unreachable from the client network. Try curl -sS https://api.triggo.dev/healthz. If that fails the server is down; if it succeeds the URL in the client config is wrong.
• Workflow tools missing from tools/list — the key validated but does not carry the workflows:read / workflows:write scopes, so the workflow tools' pre-flight scope check filters them out. Edit the key in Agent Setup and grant those scopes (both are canonical and mintable today), or mint a new key with them selected.

Related

• Agent integration overview — REST vs MCP decision guide.
• API Keys — scopes, rotation, revocation.
• Publishing Workflows as Actions — turning a workflow into something list_actions can see.