Claude Desktop

If your server runs in google auth mode with PORTUNI_PUBLIC_URL set, use the Custom Connector (OAuth) path instead — one URL, a Google login, no token to copy. This page’s mcp-remote bridge is the fallback: it’s what you need for a solo/legacy (env auth mode) server, or any client that hasn’t added connector support.

Claude Desktop speaks MCP, but it cannot attach a bearer header to a remote server itself. The bridge is mcp-remote, which runs as a local stdio server and forwards every call to https://<server>/mcp with your device token.

What you need

1. A central Portuni server (see Team Setup) and a Google account in one of its allowed domains.
2. A device token: in the desktop app open Settings → Účet → Device tokeny and create one. It is shown once; it inherits your current role and can be revoked from the same place.
3. Node.js on the machine running Claude Desktop (npx is used to start mcp-remote).

Configuration

Add Portuni to claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config):

{
  "mcpServers": {
    "portuni": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.yourcompany.com/mcp",
        "--header",
        "Authorization:${PORTUNI_AUTH}"
      ],
      "env": {
        "PORTUNI_AUTH": "Bearer ptk_..."
      }
    }
  }
}

The ${PORTUNI_AUTH} indirection (with no space after Authorization:) works around Claude Desktop splitting arguments on spaces; mcp-remote substitutes the variable from env. Restart Claude Desktop afterwards; the Portuni tools appear under the hammer icon.

What works from here

There is no local mirror on this machine, so the tools behave like a remote agent’s:

• Graph: portuni_get_context, portuni_get_node, portuni_list_nodes, actors, responsibilities, events — everything your role allows, filtered by node visibility.
• Files: portuni_list_files lists a node’s files; portuni_read_file(node_id, path) reads the content straight from the remote (Google Drive) when no mirror exists; portuni_search_files(query) searches file contents through the remote’s own full-text search and returns only files of nodes you can see. Open a hit with portuni_read_file.
• Writes that need a disk (portuni_store, portuni_pull, portuni_mirror, portuni_adopt_files) do not apply here; portuni_snapshot works — the server exports the document and registers the file remote-direct.

Scope

A Claude Desktop session starts outside any mirror, with no home_node_id on the connection URL, so its read scope is empty. Start with portuni_session_init naming the node you work on (an organization seeds all its projects, processes and areas at depth 1), or let the tools’ scope_expansion_required answers guide you to portuni_expand_scope. Reaching a node connected by a graph edge to something already in scope auto-expands silently; a disconnected jump (a node found only via search or name, with no edge path) asks you to confirm first, either via a real dialog (if Claude Desktop declares the MCP elicitation capability) or the portuni_expand_scope round trip. portuni_search_files and portuni_list_nodes(scope: "global"), on the other hand, are discovery — permission-only, no scope gate at all, so they never need this dance; only opening a hit in full (portuni_read_file, portuni_get_node) is the scope event. See Scope Enforcement.