Connect your agent

Search, read, and prepare project contributions from the AI client you already use. You review permissions and publication separately.

GET STARTED

node packages/runner/dist/cli/bin.js mcp add --client claude-code --registry http://localhost:3000

From a built repository checkout. Requires Node.js 22+ and your installed AI client. Review registration, then sign in.

Build the CLI & connect your agent →

Before you connect

For command setup, install Node.js 22 or newer and Claude Code, Codex CLI, or Gemini CLI. Other clients can use their native configuration instructions below directly. Use an interactive terminal; the CLI shows the exact registration command and asks for confirmation.

The localfirstdotsh package is built from this repository until it is published to npm. From a repository checkout, install dependencies and build the CLI:

pnpm install --frozen-lockfile && pnpm build:contracts && pnpm --filter localfirstdotsh build

Run from the repository root, then copy the connection command above.

The command targets http://localhost:3000. It discovers this registry’s MCP endpoint; it does not install a model or execute project code.

WORKS WITH AI TOOLS

Connect over MCP. Choose your client for setup instructions.

Claude (claude.ai and Claude Desktop)

Add Localfirst as a custom connector by URL. No terminal is needed.

Server URL unavailable

The registry’s MCP endpoint could not be discovered. Try again or consult your registry operator.

On Free, Pro, or Max, open Customize → Connectors → Add custom connector, paste the URL, and click Add.
On Team or Enterprise, an Owner opens Organization settings → Connectors → Add → Custom (choose Web) and pastes the URL. Each person then opens Customize → Connectors, finds the connector marked Custom, and clicks Connect.
If Claude asks how it identifies itself to the server, choose Register automatically. Sign in with GitHub in your browser and review the permissions requested.

Free accounts can add one custom connector. Turn Localfirst on or off per conversation from the + menu. Custom connectors reach services Anthropic has not verified, so connect only a registry you trust.

Claude custom connector documentation

ChatGPT

Add Localfirst as a custom MCP server by URL. Custom MCP servers are limited to certain plans and workspace roles, so ask your workspace admin if you do not see the option.

Server URL unavailable

The registry’s MCP endpoint could not be discovered. Try again or consult your registry operator.

Open ChatGPT Plugins, select +, then Add custom MCP server.
Enter a name and description, choose Public endpoint, and paste the URL. It must include the /mcp path.
Choose OAuth for authentication, acknowledge the risk warning, and create it. Sign in with GitHub in your browser, then review the tools ChatGPT discovered.

OpenAI has moved these menus before; if yours differ, follow OpenAI’s current help article.

ChatGPT custom MCP server documentation

Claude Code

Choose Claude Code above. Localfirst runs claude mcp add --transport http using the discovered endpoint, with user scope by default. Review and confirm the command, then open /mcp in Claude Code, choose Localfirst, and sign in in your browser.

Codex CLI

Choose Codex CLI above. Localfirst runs codex mcp add with the discovered endpoint. Codex starts its own browser sign-in. If sign-in was interrupted, run codex mcp login localfirst.

Gemini CLI

With a current source build, choose Gemini CLI above. Localfirst runs gemini mcp add --transport http --scope user with the discovered endpoint. Review the command and confirm registration, then run /mcp auth localfirst inside Gemini CLI and complete browser sign-in. Tool approvals stay enabled.

Gemini CLI MCP documentation

Cursor

Cursor CLI uses the same MCP configuration as the editor. Merge the localfirst entry below into ~/.cursor/mcp.json for global access, or .cursor/mcp.json in your project. Preserve your other servers and settings.

Connection configuration unavailable

The registry’s MCP endpoint could not be discovered. Try again or consult your registry operator.

In Cursor CLI, run agent mcp login localfirst to sign in and review access, then check agent mcp list. In the editor, authenticate from MCP settings when prompted.

Cursor CLI MCP documentation

OpenCode

Merge the localfirst entry into the mcp object in your project’s opencode.json or opencode.jsonc. Preserve existing providers, servers, and other settings. OpenCode discovers OAuth from the remote server.

Connection configuration unavailable

The registry’s MCP endpoint could not be discovered. Try again or consult your registry operator.

Run opencode mcp auth localfirst to open browser sign-in and review permissions. Check registration with opencode mcp list. You can also use the interactive opencode mcp add wizard to add the same remote endpoint.

OpenCode MCP documentation

GitHub Copilot

For Copilot CLI, merge the localfirst entry into ~/.copilot/mcp-config.json. It uses the mcpServers format below. Preserve existing servers and review requested access when Copilot starts browser sign-in.

Connection configuration unavailable

The registry’s MCP endpoint could not be discovered. Try again or consult your registry operator.

Inside Copilot CLI, use /mcp auth localfirst if sign-in is needed, then /mcp list to inspect the server. The tools list makes tools available; it does not replace your consent or tool approvals. VS Code Copilot uses a different configuration format; use its MCP settings for editor setup.

GitHub Copilot CLI MCP documentation

VS Code

Run MCP: Open User Configuration (all workspaces) or edit .vscode/mcp.json in a workspace, and merge this entry into the servers object. VS Code uses servers, not mcpServers. Preserve existing servers.

Connection configuration unavailable

The registry’s MCP endpoint could not be discovered. Try again or consult your registry operator.

Start the server from MCP: List Servers, then complete the browser sign-in VS Code opens and review the tools it offers before using them.

VS Code MCP documentation

Windsurf

For Windsurf’s Cascade agent, open the Cascade panel’s MCP settings and choose the raw configuration or Open MCP config file action. Merge this entry into mcpServers in the file your installed app opens, preserving other settings.

Connection configuration unavailable

The registry’s MCP endpoint could not be discovered. Try again or consult your registry operator.

Save and refresh the server list, enable Localfirst, and complete the client’s OAuth sign-in when prompted. These instructions target Cascade; newer builds with a separate Devin Local agent use different MCP configuration. Team administrators may need to enable MCP access.

Windsurf Cascade MCP documentation

Cline

In the Cline extension, open MCP Servers → Configure → Configure MCP Servers and merge the entry below. Cline CLI uses ~/.cline/data/settings/cline_mcp_settings.json unless its settings path is overridden. Keep type: streamableHttp explicit and preserve existing servers.

Connection configuration unavailable

The registry’s MCP endpoint could not be discovered. Try again or consult your registry operator.

For guided setup, run cline mcp, or use the extension’s Remote Servers tab and select Streamable HTTP. Complete browser authorization from the client’s OAuth action when requested. The empty autoApprove list keeps tool approval with you.

Cline MCP documentation

What your agent can do

These are the tools Localfirst gives a connected client. Which ones work depends on the permissions you grant when you sign in. None of them can reach your computer, run a model, or execute project code.

Read only

Look things up. These change nothing.

project_search — Search local-AI projects
project_get — Get a project specification
project_check_compatibility — Assess declared compatibility
project_get_derivatives — Read attributed lineage
reference_get_relationships — Read model or hardware relationships
comparison_get_groups — Compare accepted public reports
community_list — Read curated community knowledge
test_get — Get a test definition
test_plan_local — Get a generic local test plan
test_get_result — Get a test result
test_get_verifications — Read independent verification provenance
build_get — Get a build
build_get_evidence — Get accepted evidence
draft_get — Get your draft

Save privately

Write drafts, builds, reports, or notes that only you can see until you publish.

contribution_create_draft — Create a contribution draft
project_create_derivative_draft — Create an attributed derivative draft
draft_update — Update your draft
draft_validate — Validate your draft
build_save — Save a private build
test_submit_result — Submit a sanitized test result
community_save — Save a private community contribution

Publish

Make a draft public. You approve that exact version in your browser first; the agent cannot approve it for you.

contribution_publish — Publish an approved contribution

Stay in control

Turn on your client’s tool-approval setting so you can review each call before it runs, and use Always allow only for read-only tools.
Project descriptions are written by other people. A connected agent reads them as data, but treat anything that tells your agent to do something as untrusted, especially if you have other servers connected.
Review the permissions on the sign-in screen. Publishing always needs your approval of the exact version in your browser.
On a work or school network, your IT administrator may need to allow the registry host.

Review access, then explore

Sign in with GitHub when your client asks, and review its requested permissions.
Ask your agent to search projects or read a specification.
To publish, ask it to prepare a draft. Review the exact version at the approval link before your agent publishes it.

Local AI ecosystem

The source runner has adapters for Ollama and LM Studio. Discovering installed models and running a test are separate local actions, with their own plan and approval. These runtimes are not MCP hosts configured by this connection command.

Aider and Goose are not listed as supported integrations here. Configuration-based integrations use each client’s native setup; the Localfirst CLI offers automatic registration only for the clients in its selector.

Check access and confirm the connection

Ask your agent to search for a public project and read an exact version. Public REST catalog reads are available without sign-in; authenticated MCP access and private draft operations require the appropriate permissions.

Request only the scopes your task needs. Preparing drafts uses projects:draft; publication uses projects:publish and separate approval of the exact artifact. A registry connection cannot run a model on your machine.

Review or revoke client access in Connections. Keep registry tokens separate from GitHub and local runtime credentials.

Client support and troubleshooting

The official MCP SDK exercises discovery, tool calls, and resource reads. Claude Code has exercised discovery and read-only environment tool calls in a real model session. Its browser OAuth flow is not established by that test. Codex CLI configuration has been checked; a live model-session connection is not claimed. Other desktop clients remain untested here.

Unauthorized: reconnect through the client's supported authentication flow. A REST token and an MCP token have different audiences and are not interchangeable.
Insufficient scope: review the permission needed for the requested action and authorize it deliberately.
Endpoint or transport error: confirm the URL ends in /mcp and the client supports Streamable HTTP. Opening the endpoint as a browser GET is not a connection test.
Unsupported client: use the REST API reference and project schema as a fallback. Do not assume an untested client works.

Next: write a project specification, test locally, or set up a business environment.