Connect with an API key

An API key reaches the same MCP server as the Claude and ChatGPT connectors, with no browser sign-in. Use it when the caller is a program: your own MCP server, a scheduled job, or an agent running without a person at a browser.

If you are an agent setting this up, follow the steps in order. Step 1 needs a person. You can do everything after it.

1. Create a key

A workspace member with the Manage API Keys permission does this once.

1. In Havilo, open Settings → Advanced → API Keys.
2. Select Create API key, name it after where it will run, and change the preset to AI Assistant.
3. Copy the key. It is shown once.

The key acts as the person who created it. It can do only what both that person and the key are allowed, and it stops working if that person leaves the workspace. If the page says API access isn't enabled for this workspace, ask your Havilo contact.

Store the key as HAVILO_API_KEY. Never put it in a prompt, a file you commit, or a URL.

2. Connect

Server URL:

https://havilo.ai/api/mcp

Send the key as a bearer token on every request:

Authorization: Bearer <HAVILO_API_KEY>

Claude Code:

claude mcp add --transport http havilo https://havilo.ai/api/mcp \
  --header "Authorization: Bearer $HAVILO_API_KEY"

Your own server, with the TypeScript MCP SDK:

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const havilo = new Client({ name: 'my-server', version: '1.0.0' })

await havilo.connect(
  new StreamableHTTPClientTransport(new URL('https://havilo.ai/api/mcp'), {
    requestInit: { headers: { Authorization: `Bearer ${process.env.HAVILO_API_KEY}` } },
  })
)

const { tools } = await havilo.listTools()

const found = await havilo.callTool({
  name: 'crm_records_search',
  arguments: { query: 'Jane Doe', limit: 5 },
})
// found.structuredContent.records, or found.isError with the reason in found.content[0].text

Any other MCP client works the same way: Streamable HTTP transport, that URL, that header.

3. Check the connection

Call workspace_whoami. client_id starts with api-key: and workspace_id is the workspace the key was created in. Then call workspace_capabilities. The Engine tools need AI_FEATURE_ACCESS in that list.

4. Install the skill

The skill teaches an agent when to look a record up and when to commission the Engine, and how to follow a run to its result. Save it into your agent's skills folder. For Claude Code:

mkdir -p .claude/skills/havilo
curl -fsSL https://havilo.ai/skills/havilo/SKILL.md -o .claude/skills/havilo/SKILL.md

A server that exposes Havilo to its own clients passes the same text on: in its MCP instructions, or in the system prompt of the agent it runs.

5. Try it

Ask for a person you know is in the workspace:

Use Havilo to find Jane Doe.

Then a question about a whole group:

Use Havilo to find mentors with fintech experience who have worked in Japan.

The second one takes a few minutes. The agent starts a run, waits for it, and links the table it produces.

What a key can reach

A key cannot create, change or delete records, notes or drafts. ai_run saves the tables it makes to the workspace; crm_records_query writes its table unsaved, and crm_artifacts_save saves it. The AI tools spend the workspace's credits. Inputs and results are in the tool reference.

Limits

• 100 requests a minute per key.
• A workspace has a cap on runs in flight at once and a daily cost cap, set by its plan. ai_run refuses a run past either and says which cap and its limit.
• Every tool call is recorded in the workspace audit log with the tool it called and whether it worked.

Revoke a key from the same Settings page.

Errors

A refused connection returns JSON with error and error_description:

A tool that refuses returns a normal MCP result with isError: true and a sentence naming what was missing.