The oHallo MCP server

Alongside letting you build your own MCP servers for the platform to call, oHallo exposes its own MCP server. You can point an MCP client or an agent at it and work with your oHallo data and actions directly: knowledge base, policies, conversations, contacts, accounts, and agent definitions. It authenticates with a normal API key, and every tool is gated by that key’s scopes, exactly like the REST API.

Endpoint

POST https://api.ohallo.eu/api/mcp

The server speaks JSON-RPC 2.0 over HTTP and implements the standard tools/list and tools/call methods.

Authentication

Send your API key as a Bearer token:

Authorization: Bearer sf_live_v1_...

The key resolves your account. Each tool checks the key’s scopes and returns a permission_denied error if a required scope is missing, so grant the key the scopes for the tools you intend to call. See Authentication for the scope catalogue.

Listing the tools

curl -X POST https://api.ohallo.eu/api/mcp \
  -H "Authorization: Bearer sf_live_v1_..." \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Calling a tool

The account is taken from your key, so you do not pass it. Workspace-scoped tools take a workspace_id argument (optional when the key is itself scoped to one workspace).

curl -X POST https://api.ohallo.eu/api/mcp \
  -H "Authorization: Bearer sf_live_v1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_kb_entries",
      "arguments": { "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "query": "return policy" }
    }
  }'

Tool catalogue

Each tool requires the scope shown. This is the same permission model as the REST API, so a key that can read conversations over REST can also call the conversation read tools here.

Tool	Required scope	Purpose
get_context	any valid key	Return the account and workspace context for the key
list_workspaces, get_workspace	any valid key	List and read workspaces the key can see
list_kb_entries, search_kb_entries	kb:read	List or search knowledge base entries
create_kb_entry, update_kb_entry, approve_kb_entry, reject_kb_entry	kb:write	Manage knowledge base entries
list_policy_entries, search_policy_entries	policy:read	List or search policies
create_policy_entry, update_policy_entry, approve_policy_entry, reject_policy_entry	policy:write	Manage policies
list_conversations, get_conversation, list_attention_items	conversations:read	Read conversations and attention items
reply_to_conversation, compose_conversation, resolve_attention_item	conversations:write	Reply, compose, and resolve attention items
search_contacts, get_contact	contacts:read	Read contacts
create_contact, update_contact	contacts:write	Create and update contacts
search_accounts, get_account, get_account_contacts	accounts:read	Read accounts
create_account, update_account	accounts:write	Create and update accounts
list_agents, get_agent	agents:read	Read agent definitions
update_agent_instructions	agents:write	Update an agent’s instructions

Call tools/list for the authoritative set and each tool’s input schema; the catalogue above is a summary.

Errors

A tool returns a structured error object on failure:

{ "error_type": "permission_denied", "message": "Missing required scope: kb:write" }

Common error_type values are authentication_error, permission_denied, not_found, validation_error, and server_error.

When to use this instead of REST

Use the REST API for ordinary request and response integrations. Use this MCP server when you want an agent or an MCP-aware client to discover and call oHallo capabilities as tools, with the same account scoping and permissions as your API keys.