Skip to main content
Hyperlocalise hosts an MCP (Model Context Protocol) server so agents such as Claude Code, Codex, and Cursor can read projects, glossaries, and Board items from your workspace. The server uses OAuth with PKCE. After you approve access, the agent receives a bearer token scoped to one organization and your current membership role.

​
Connect an agent

Open your workspace Overview. The Connect your agent card shows setup snippets for Claude, Codex, and Cursor. Replace the host with your Cloud origin when developing locally, for example http://localhost:3000/mcp. The first connection opens a browser sign-in and consent flow. Pick the organization the agent should use. Codex may also require codex mcp login hyperlocalise after adding the server.
MCP auth is separate from organization API keys and personal access tokens. Agents authenticate through OAuth, not x-api-key.

​
Endpoint and discovery

OAuth authorize, token, and consent flows live under /mcp/authorize, /mcp/token, and related paths.

​
Available tools

Tool responses are JSON text in MCP content blocks. Errors use { "error": "<code>", "message": "..." }.

​
Projects and glossaries

​
Board (issues)

create_issue and update_issue require a role that can write translations back (admin or localization manager). Other roles receive forbidden. create_issue accepts optional idempotencyKey. When set, Hyperlocalise stores the issue under mcp:<key> and returns the same issue on retry unless the payload changes. list_issues supports the same filters as the workspace Board API, including view, status, issueType, priority, locale, assignee, projectId, search, sort, sortDir, limit (max 50), and offset.

​
Reserved (not implemented)

These tools are advertised but return not_implemented today:
  • list_translations
  • upload_sources
  • download_translations
  • run_workflow
Use the public API or CLI for file upload, download, and job orchestration until these tools are wired.

​
Outbound MCP in automations

To let a saved automation call a remote MCP server (Semrush, Ahrefs, or your own), add an MCP Server connection under Integrations, then enable the MCP tool on the automation. That path is outbound from Hyperlocalise to a third-party server and is unrelated to the hosted /api/mcp server agents connect to. See Integrations.

​
Permissions and scope

An MCP session inherits your live organization membership:
  • Project and glossary reads respect team and project access.
  • Issue writes follow the same rules as the Board UI.
  • Revoking your membership or disabling MCP auth ends the session on the next refresh.
Token lifetime defaults to 60 minutes with a 30-day refresh window. Operators can tune these with MCP_TOKEN_LIFETIME_MINUTES and MCP_REFRESH_TOKEN_LIFETIME_DAYS.

​
Troubleshooting

​
Next