Connecting your tools

Anything that speaks MCP can connect to a workspace, and anything that can make an HTTP request can use the REST API. You'll find everything below, with your real URLs filled in, under Connect agents in the sidebar.

Two ways in

Signing in is for people. You add the server to your AI tool, it sends you to a sign-in page, and from then on the agent acts as you. It sees what you can see (including your private notes) and can suggest edits to what you can edit. If your access changes, the connection follows. Nobody has to hand out or rotate anything.

An API key is for everything else: tools that can't do a sign-in flow, automations, scripts, and people outside your organization like an agency or a contractor. A key is a long string starting with cmcp_ that goes in an Authorization header. See API keys for the kinds of key and what each can do.

If your tool supports signing in, sign in. It's less to manage, and it stops working by itself when someone leaves.

Two URLs

The Connect agents page shows two addresses.

The sign-in URL ends in /api/mcp. It's the same for every workspace. A sign-in connection uses your default workspace unless the agent asks for another one; every tool on this URL takes an optional workspace argument, and list_workspaces shows which ones you can reach. If you belong to more than one workspace, the Connect agents page lets you choose your default.

The workspace URL ends in /api/mcp/ followed by the workspace's id. It always means that one workspace. You can sign in on it or use an API key.

API keys work on either URL and always stay in the workspace they were made for.

Workspaces under different accounts

MCP clients keep one sign-in per URL. If you're in workspaces under different accounts (one per client, say), the shared sign-in URL can only be signed in as one of them at a time. Use each workspace's own URL instead, for example in a project's .mcp.json, and sign in on each with the account that belongs to it.

Your browser stays signed in to Herald between connections, so before signing in on a workspace that belongs to your other account, sign out of the app in your browser first. If you connect with the wrong account, the server says which account you used instead of asking you to sign in again.

Claude

Claude (on the web and the desktop app) connects by signing in.

1. Copy the sign-in URL from Connect agents.
2. In Claude, open Settings → Connectors → Add custom connector.
3. Paste the URL, give it a name your team will recognize, and save.
4. Click Connect and sign in with your Herald account.

Each person connects with their own sign-in, so everyone's Claude sees exactly what they can see in the workspace.

ChatGPT

ChatGPT also connects by signing in.

1. In ChatGPT, open Settings → Apps & Connectors and create a connector. Depending on your plan, you may need to turn on developer mode first.
2. Use the sign-in URL, with OAuth as the authentication method.
3. Sign in with your Herald account when prompted.

If you'd rather build a Custom GPT with Actions, import the OpenAPI schema from https://getherald.ai/api/v1/openapi.json and set authentication to an API key, sent as a Bearer token.

Cursor

Cursor uses an API key. Add the server to ~/.cursor/mcp.json for all your projects, or to .cursor/mcp.json in one repository:

{
  "mcpServers": {
    "tidewater": {
      "url": "https://getherald.ai/api/mcp/YOUR_WORKSPACE_ID",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Copy the workspace URL from Connect agents rather than typing it. To sign in instead of using a key, leave out headers. Don't commit a project file with a real key in it; use a personal key in your home directory instead, or your team's usual way of handling secrets.

Claude Code

With an API key:

claude mcp add --transport http tidewater https://getherald.ai/api/mcp/YOUR_WORKSPACE_ID --header "Authorization: Bearer YOUR_API_KEY"

Or sign in instead, using the sign-in URL:

claude mcp add --transport http context https://getherald.ai/api/mcp

Then run /mcp inside Claude Code and choose the server to sign in.

To keep one project on one workspace, sign in on the workspace URL and save it with the project:

claude mcp add --transport http --scope project tidewater https://getherald.ai/api/mcp/YOUR_WORKSPACE_ID

This writes .mcp.json with no key in it, so it's safe to commit. Each workspace URL keeps its own sign-in, so different projects can use different accounts.

Other MCP clients

The server uses the Streamable HTTP transport. Point your client at either URL and authenticate with Authorization: Bearer YOUR_API_KEY, or with OAuth if the client supports it (the server advertises its authorization server in the standard way).

For a client that only supports local stdio servers, bridge it with mcp-remote:

{
  "mcpServers": {
    "tidewater": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://getherald.ai/api/mcp/YOUR_WORKSPACE_ID",
        "--header", "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

n8n, Zapier and your own code

For workflows and scripts, the REST API is usually simpler than MCP. One call gets the context for a task:

curl -X POST https://getherald.ai/api/v1/context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Welcome email for a clinic that just signed up for the Team plan", "format": "markdown"}'

The Markdown that comes back is ready to drop into a prompt. In n8n, that's an HTTP Request node before your AI node; in Zapier, a Webhooks step. The full API is in the REST API reference, and the OpenAPI spec at https://getherald.ai/api/v1/openapi.json can be imported into most tools that understand one.

Checking it works

Give your agent a real task and watch for a get_context call before it writes. Then open Activity in the app (if you're an owner or admin) and you'll see the request, which pack it matched and which pages went back.

If your agent doesn't call the tools on its own, there are a few things to try in Troubleshooting. The most effective is usually a line in the workspace's agent instructions, plus telling the agent once in your own words. For Claude specifically, Instructing Claude has wording to copy.

What an agent can do once connected

Every connection can read: get_context, search, get_structure, list_pages, read_page, get_file, list_packs and list_tags. Connections that can edit also get tools to create and edit pages, which save as drafts. Sign-in connections always get the editing tools, because anyone can at least keep private notes; what they're allowed to change is checked on every call. The full list is in MCP tools.