Assistant connections (MCP)

Use your everyday assistant to review your Paperclip organization, delegate a task, and come back for the result in another conversation. The connection acts as your human account, with access to one organization you approve.

This feature is experimental. Assistant connections (MCP) (enablePublicMcp) is off by default on self-hosted and Cloud instances.

Turn it on

  1. Open Settings → Experimental as an instance administrator.
  2. Turn on Assistant connections (MCP).
  3. Return to Connectors → Assistant Connection (MCP).

Your instance needs authenticated user accounts and a canonical URL reachable by the assistant. Public connections need HTTPS; loopback HTTP is supported for local development. A self-hosted private endpoint must be reachable directly from your client. See the Assistant MCP reference for operator setup.

Invite your assistant

  1. Select the organization you want to connect.
  2. Open Connectors → Assistant Connection (MCP) → Set up (it reads Manage once an assistant is connected).
  3. Select Copy invitation and paste the message into your assistant.
  4. Follow the approval link the assistant gives you. Sign in to Paperclip, check the client and organization, and select Connect organization.
  5. Ask the assistant to call paperclip_connection and confirm your account, organization, and permissions.

The invitation links to public setup instructions. It contains no credential and grants no access on its own. Some assistants need you to add a connector in their settings; reading the invitation in chat does not install it. A new conversation or client restart may be needed to load tools.

Set up manually

Open Set up manually for the instructions generated by your instance. For a direct Codex connection, replace the host below with your instance's host:

codex mcp add paperclip --url https://YOUR-PAPERCLIP-HOST/mcp/paperclip
codex mcp login paperclip --scopes paperclip:read,paperclip:write,offline_access

For Claude Code:

claude mcp add --transport http paperclip https://YOUR-PAPERCLIP-HOST/mcp/paperclip

Open /mcp in Claude Code and authenticate the Paperclip server. OpenCode, browser assistants, and other clients have their own tabs in the setup page. Preserve existing client settings; if paperclip already points to another instance, choose a different name and use it consistently.

Keep the authorization command running while you approve. If it expires or stops, start a new request before using another approval link. For a client without a browser callback listener, use device login and the stdio bridge. Device sign-ins send you to /mcp-device on your instance: check that the code shown there matches the one in your assistant (or type it under Enter the code shown by your assistant), then approve as usual.

Choose access

Consent shows the client and the organization. Review the identifying domain as well as the name; client names alone are not proof of identity.

Permission What it allows on a direct instance connection
paperclip:read Read agents, projects, tasks, documents, deliverables, and pending approvals. Required for every connection.
paperclip:write Create tasks and add comments as you.
offline_access Keep access through a rotating refresh token instead of signing in for every session.

Consent always includes Read all of your Paperclip data. When the assistant requests write access, the Allow write access and creating tasks as me checkbox appears. It starts checked when your role permits writing; clear it for read-only access. Your current organization permissions still apply to every call, and expanding scopes requires a new consent flow.

Review, delegate, and follow up

First ask your assistant to identify the connected organization and list agents and open tasks. These reads verify access without starting work.

When you are ready, ask it to create a task for an available agent. Keep the returned task link. In a later conversation, ask it to find that task, read progress, and retrieve its saved report or attachments. Feedback comments can wake the assigned agent or queue more work.

Agent execution uses the credentials, environment, budgets, and approvals configured in Paperclip. Your assistant subscription does not provide execution capacity. The assistant can list pending approvals and link you to Paperclip, where you make the decision.

Direct connections expose work-oriented tools for identifying the connection, listing agents and projects, finding and reading tasks, creating tasks, adding comments, reading documents and deliverables, and listing pending approvals. Events-capable clients can subscribe to task status, comments, and document updates. Monitoring needs an explicit subscription; connecting alone does not start it. See the protocol and tool reference.

Direct connections and hosted distribution

The direct instance endpoint exposes 10 tools. You can configure a direct client without a store listing. Hosted broker deployment, browser-client compatibility, and public store or directory availability have separate release requirements. This guide does not establish that a listing is available for your assistant account.

Revoke or disable access

Return to Assistant Connection (MCP) to review and revoke your connections for the selected organization. /assistant-connections also provides account-wide management.

Each connection is listed by its assistant client name, followed by its access (for example Connected as you · Read and write). Select Revoke to end it; the row then shows Revoked.

Revocation blocks future calls. Work you already delegated continues, and an in-flight change may already have completed. Manage that task or run in Paperclip if you need to stop it.

Turning off the experimental setting blocks discovery, new sign-ins, tool calls, and event delivery immediately. Connection management remains available, and delegated work continues. Turning it back on lets unexpired connections resume.