OpenCode V2

Tier 2: configuration verified on 2026-10-21 with OpenCode v2.0.23. The server was added to a clean project, the client connected to the live broker and reported that the server needs authentication, and the written configuration was inspected. The browser sign-in and the first tool call were not completed on the verification machine.

Before you start

• OpenCode V2 installed and on your PATH. Check with opencode --version. The version used here was v2.0.23.
• A browser on the same machine, signed in to the GitHub account that owns the agents.
• A verified human account with the master delegation agreement signed. See the agent quickstart.
• The server URL has no trailing slash: https://agentregistrar.dev/mcp.

Add the server

From the project that should use the broker:

opencode mcp add agentregistrar --url https://agentregistrar.dev/mcp

Add --global to make it available in every project instead of writing the project configuration. The command wrote this file, opencode.json in the project root:

{
  "mcp": {
    "servers": {
      "agentregistrar": {
        "type": "remote",
        "url": "https://agentregistrar.dev/mcp"
      }
    }
  }
}

Each field is deliberate. mcp.servers is the V2 shape. A server name placed directly under mcp is the older V1 shape: the V2 schema marks it deprecated, but v2.0.23 still reads it, so use mcp.servers to stay on the documented shape. type is remote for a remote server. url is the Streamable HTTP endpoint. Do not add an enabled field: V2 uses disabled to keep a configured server from connecting.

To add it by hand instead, write the same object into opencode.json. There is no token field, because OAuth supplies the credential.

Authorize

Check the state first:

opencode mcp list

On a fresh configuration the server is listed as needing authentication. The client prints a status marker before the name; the output here keeps the text only:

agentregistrar  needs authentication

Start the sign-in either way:

opencode mcp auth agentregistrar

or run /mcps inside OpenCode, select agentregistrar and choose to authenticate. OpenCode opens a browser. Approve the request for the GitHub account that should own the agents. The broker's authorization server metadata advertises Client ID Metadata Documents, so V2 identifies itself with its published metadata document first and falls back to dynamic client registration. No client ID or secret is needed.

The token is stored outside the project configuration. Nothing in opencode.json changes after sign-in.

Verify the connection

opencode mcp list

The server should now read as connected. Inside OpenCode, /mcps shows the server, its state and its tool count. The broker exposes nine tools: identity_register, identity_whoami, identity_signup, identity_prove, identity_record_signup, inbox_list, inbox_read, inbox_wait_for_email and inbox_send.

OpenCode prefixes MCP tools with the server name, so identity_whoami is exposed as agentregistrar_identity_whoami. Under the default Code Mode the tools are grouped per server and called as tools.agentregistrar.identity_whoami.

First call

Ask for the identity in an OpenCode session:

Use the agentregistrar MCP server. Call identity_whoami with no arguments and show the result.

The result names the agent bound to this OAuth session, its inbox address, its scopes and its human owner. The shape below is illustrative, with synthetic ids and address. It is the identity_whoami result and is trimmed: the nested agent mirror, signup_state and docs are omitted for length.

{
  "id": "agt_01JAB2C3D4E5F6G7H8J9K0MN1P",
  "name": "opencode-agent",
  "slug": "opencode-agent-k0mn1p",
  "harness": "opencode-v2",
  "email_address": "opencode-agent-k0mn1p@agents.agentregistrar.dev",
  "status": "active",
  "scopes": ["tos:accept", "signup:free_tier", "inbox:read", "inbox:send"],
  "human_owner": { "...": "..." }
}

identity_whoami creates the default opencode-agent with harness: "opencode-v2" when the session has no agent yet. That default is the same for every client, so call identity_register with a name and harness first if you want a client-specific label. Registration is idempotent: the agent bound to the token is returned whatever name you pass later, so a different name needs a new OAuth session.

Continue

The full signup, from the first registration to a provider account and a receipt, is in the agent quickstart. The tool contract is in the reference.

Troubleshooting

If the browser does not open, opencode mcp auth prints the authorization URL; open it manually. Do not put a token in opencode.json: OAuth is the supported path.

Remove and reset

opencode mcp logout agentregistrar

That removes the stored OAuth credentials. To remove the server itself, delete its entry from mcp.servers in the project or global opencode.json; there is no mcp remove subcommand in v2.0.23. Re-add it and authorize again to start a new session with a different account.

Verification record

Tier 1 requires the missing rows above: a completed sign-in, a tool list and a full brokered signup with a transcript.