Skip to content

Connect ChatGPT, Codex, or Claude

The exact UI differs between clients, but the safety contract is the same.

Connection values

Every project has its own address. Connect each project separately with its own URL — one project, one address:

MCP server: https://mcp.heyaira.eu/p/<project-slug>/mcp
Transport: Streamable HTTP
Authentication: OAuth 2.1 Authorization Code + PKCE
Resource: https://mcp.heyaira.eu/p/<project-slug>/mcp

For example https://mcp.heyaira.eu/p/heyaira/mcp and https://mcp.heyaira.eu/p/voyana/mcp. The project owner gets the address from the operator (heyaira-admin create-project --slug … or update-project prints it as mcp_url). server_identity also returns it as project.mcp_url.

Before the first sign-in

There is no self-service sign-up. The OAuth consent page asks for the project's access token and accepts nothing else: not a password, not an OAuth token. Only the operator command heyaira-admin create-project --token-file … issues that token, once, when the project is created; it is written to a file and never printed. Ask the operator for the project's address and its access token before you connect a client. The token selects the project and your role at consent; it is not passed to the client.

Because the URL is different for each project, one client (for example one claude.ai organization) can hold a connector for every project side by side. Consent shows the project the address belongs to; a project access token of any other project is refused. A grant issued for one project's address is rejected on every other address.

The instance-wide https://mcp.heyaira.eu/mcp is deprecated. It still works and still issues new grants, but connect new clients with the per-project address.

Listing values

When a client asks for a name, description, icon, or website for the connector, use the approved values so HeyAira reads the same everywhere:

Name: HeyAira – <Project name>   (for example "HeyAira – Voyana")
Description: Keep your project's decisions, tasks and handoffs across the AI tools you choose.
Website: https://heyaira.eu
Icon: HeyAira-AppIcon-Light-1024x1024.png (official single blue dot)

Always write the name as one word, HeyAira, followed by the project name so each connector says which project it opens. Developer, category, and website fields are stored by the client, not by the MCP server, so update them in the client's connector or app settings.

Do not paste a token into a repository, prompt, screenshot, or shared note. Complete OAuth consent in the client. A client connection represents an OAuth grant; repeated reconnects can leave stale grants that require revocation.

Verify before writing

Run a read-only check first:

  1. server_identity
  2. continuity_context
  3. compare the returned project (name and id) and resource with the operator-selected connection profile; identity.resource is the address you connected to
  4. only then allow a mutation

If the client exposes an old tool schema, reconnect it before attempting a write. In particular, current write tools require write_context; do not try to bypass this requirement.

Client-specific notes

Use the client’s connector or MCP settings to reconnect. The server cannot repair a stale OAuth grant stored by a client. If multiple entries for HeyAira appear, keep the working grant for the intended project and remove stale entries only after checking their target.

Agents started by the Bridge

Agents that the HeyAira Bridge runs for a task do not use a client connection. Each gets a task-scoped credential from the server, delivered by the Bridge, that reads only its assigned task version and project memory and records its result. See send a task to an agent.

What success looks like

A successful connection can discover the current tools and complete both read-only calls. A successful connection is not proof that a write is safe until the returned identity matches the selected project and instance.