Connect an AI agent to Handover with MCP

What does the Handover MCP server provide?

The MCP server exposes native tools for search, artifact reading, creation, continuation, comments, annotations, assignments, imports, and exports. The agent uses the same organization and handover access rules as the web application.

Which identity should I use?

Use browser OAuth for an interactive MCP host and a named service identity for unattended automation. Codex, Claude Code, Gemini CLI, Cursor, Gatana, and other standards-compatible hosts can discover Handover's authorization server, register a public client, and sign each person in without a copied employee token.

• Never share one employee's token across a team.
• Create one service identity per agent or agent profile.
• Grant read-only access unless the agent must publish or continue context.
• Revoke a credential without disabling the person who created it.

How do I connect an unattended agent?

Create an agent identity in Company or Workspace → Agents, choose the minimum read or write scopes it needs, and save the credential when it is shown. Send that credential as a bearer token to the hosted streamable HTTP endpoint.

{
  "mcpServers": {
    "handover": {
      "type": "streamable-http",
      "url": "https://handover.sh/api/mcp?profile=core",
      "headers": {
        "Authorization": "Bearer <HANDOVER_TOKEN>"
      }
    }
  }
}

How do I connect Claude Code?

Add the hosted Streamable HTTP endpoint at user scope. Claude Code follows Handover's OAuth discovery metadata and opens the browser sign-in flow when it connects.

claude mcp add --transport http --scope user handover \
  https://handover.sh/api/mcp?profile=core

What protects browser authorization?

Handover accepts public MCP clients through dynamic client registration, requires authorization code + PKCE S256, validates exact redirect URIs, issues short-lived access tokens, and rotates refresh tokens. Replaying an already-used refresh token revokes its whole token family.

• The consent screen shows the client name, signed-in person, company, and requested scopes.
• OAuth cannot grant service-credential management.
• Tokens remain bound to the approving principal, organization, workspace, and storage cell.
• A person can reconnect after revocation without affecting a separately named service agent.

How do I verify the connection?

Ask the host to call handover.whoami, search for a known handover, read its current revision, and list open annotations. The returned identity, organization, and scopes should match the credential you created.

• The host should list Handover's native tools.
• Search must only return context visible to that identity.
• A write must be attributed to the person or service agent that authenticated.
• A revoked credential must stop working immediately.

What is the recommended agent handoff sequence?

Search before creating duplicate context, read the current revision and open annotations, continue with optimistic concurrency, then resolve feedback addressed by the new revision.

• Call handover.search to find related work.
• Call handover.get and handover.annotations before writing.
• Call handover.continue with the current expectedRevisionId.
• Call handover.update_comment for annotations the revision resolves.

Can an agent mention a person or another agent?

Yes. An agent can include mentionPrincipalIds when it creates a comment or annotation. Only principals that already have access to the handover can be mentioned, and a mention never grants access.