Connect an AI Agent

Connect an AI agent to Shout and it can list your forms, summarise responses, look up contacts, and triage your support inbox — in plain language, no code. Shout ships a first-class MCP server for exactly this, and it works with any MCP-capable client.

This page walks through connecting the popular clients, one by one. Once connected, try the agent recipes for prompts that work well.

Beta

As with the REST API, https://publicapi.shout.com is not live yet — during the beta use the base URL we provide, with /mcp appended.

Before you start: create an API key

Every client below authenticates with a Shout API key.

1. Sign in to Shout as a tenant admin, click your avatar, choose Developers, and open the API keys tab. (API access is included on Professional and Business plans.)
2. Click Create key, name it after the client (e.g. “Claude Code”), and select scopes.
3. Copy the key — it starts with sk_ and is shown only once.

Give agents a read-only key

For agent sessions, select only read scopes: forms:read, responses:read, contacts:read, tickets:read. Form responses and ticket messages are written by strangers on the internet, and if one of them ever tricks the agent (a prompt injection), a read-only key means it still can’t send emails, change data, or create contacts. Grant write scopes only to a key used in flows where a human reviews each action before it runs — see MCP security.

Your data and AI providers

Connecting an agent doesn’t just connect a client app — it connects an AI model provider. Before you connect one, be clear about where your data goes:

• Tool results flow to your AI provider. Whatever the agent retrieves from Shout — including your contacts’, respondents’ and customers’ personal data — is sent into the context of the AI model provider behind your agent (for example Anthropic for Claude, or OpenAI for a Custom GPT), and is handled under that provider’s terms and data-use policies.
• That provider is a recipient you engage, not Shout. Under data protection law (such as the GDPR), the AI provider is a recipient you appoint. You are responsible for that disclosure, for any international data transfer it involves, and for your own transparency obligations — telling your respondents and customers, in your privacy notice, that their data may be processed by your AI provider.
• Prefer read-only keys for autonomous agents. Use read-only API keys for agent sessions that run without supervision; grant write scopes only where a human reviews each tool call before it runs (see the key-creation guidance above).

See our Data Processing Agreement for how Shout processes your data as a processor; your AI provider is not a Shout sub-processor — it is a recipient you appoint.

The connection details every client needs:

Setting	Value
Server URL	https://publicapi.shout.com/mcp
Transport	Streamable HTTP
Auth header	Authorization: Bearer sk_your_key

Claude Code

One command:

claude mcp add --transport http shout https://publicapi.shout.com/mcp \
  --header "Authorization: Bearer sk_your_key"

Then in a Claude Code session, try:

Use the shout whoami tool, then list my forms.

To make the server available in every project, add --scope user. To keep the key out of your shell history, put it in an environment variable and reference it from .mcp.json instead — Claude Code expands ${SHOUT_API_KEY} in header values.

Claude Desktop

Add the server to claude_desktop_config.json, then fully quit and reopen Claude Desktop (the file is read once, at startup):

{
  "mcpServers": {
    "shout": {
      "url": "https://publicapi.shout.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_your_key"
      }
    }
  }
}

The config file lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

After restarting, the Shout tools appear in the tools menu. Ask Claude to “call the Shout whoami tool” to confirm the connection.

Claude on the web (claude.ai)

Custom connectors on claude.ai are added under Settings → Connectors → Add custom connector (on Team/Enterprise, an Owner adds them under Admin settings → Connectors). Enter https://publicapi.shout.com/mcp as the URL.

There’s one catch: the custom connector dialog authenticates with OAuth by default, and Shout’s MCP server uses API keys. Anthropic is rolling out request-header authentication for custom connectors (in beta as of July 2026):

• If your Add custom connector dialog shows a Request headers section, add a header named Authorization with the value Bearer sk_your_key — including the word Bearer and the space, exactly as your server expects to receive it. Mark it Required, then click Add.
• If you don’t see a Request headers section yet, your account doesn’t have the beta — use Claude Desktop or Claude Code (above) instead, which support API-key headers today.

ChatGPT

ChatGPT’s custom MCP connectors (Settings → enable Developer mode, then add an app/connector for your MCP server) support OAuth or no authentication only. OpenAI’s documentation is explicit that ChatGPT cannot present custom API keys or static headers to an MCP server — so ChatGPT cannot currently connect to Shout’s MCP server, which authenticates with API keys. We’d rather tell you that than have you burn an hour on it. If OpenAI adds header-based authentication, we’ll update this page.

What works today instead: a Custom GPT with Actions calling the Shout REST API directly. GPT Actions support API-key authentication — create one, set authentication to API Key / Bearer, paste a read-only Shout key, and give it an OpenAPI description of the endpoints you want (start with GET /v1/forms and GET /v1/forms/{id}/responses).

Cursor

Create (or edit) ~/.cursor/mcp.json — or .cursor/mcp.json in a project for a project-scoped setup:

{
  "mcpServers": {
    "shout": {
      "url": "https://publicapi.shout.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_your_key"
      }
    }
  }
}

Cursor picks the server up from Settings → MCP, where you can verify it shows a green status and its tool list. To keep the key out of the file, Cursor resolves environment variables in header values: "Authorization": "Bearer ${env:SHOUT_API_KEY}".

Any other MCP client

Shout’s MCP server is standard streamable HTTP, so any client that supports remote MCP servers with a custom header can connect:

• Endpoint: https://publicapi.shout.com/mcp
• Transport: streamable HTTP (some clients call it http or streamable-http; the server is stateless, so no session affinity is needed)
• Auth: send Authorization: Bearer sk_your_key on every request (X-Api-Key: sk_your_key also works)
• No OAuth flow — if your client only supports OAuth for remote servers, it can’t connect yet

If the client supports a “test connection” step, it should complete the MCP initialize handshake and list 16 tools — see the tool reference.

Check it’s working

Ask the agent to call whoami. It requires no scope and returns the key’s name, your tenant and the scopes the key actually holds — the fastest way to confirm both the connection and what the agent is allowed to do.

Troubleshooting

Symptom	Meaning	Fix
401 Unauthorized	Missing, mistyped, expired or revoked key.	Check the header is exactly Bearer sk_...; create a fresh key if in doubt.
403 plan_required	The key is valid but your plan doesn’t include API access.	Upgrade to Professional or Business; existing keys start working within a couple of minutes.
Tool error naming a scope	The key lacks that tool’s scope.	Create a key with the scope — or take it as a sign your read-only key is doing its job.
429 Too Many Requests	Rate limit: 120 requests per minute per key.	Wait for the Retry-After interval; ask the agent to batch less aggressively.
Tools listed but calls fail	Tool listing isn’t filtered by scope — seeing a tool doesn’t mean the key can use it.	Call whoami to see the key’s actual grants.