Skip to content

feat(harness): sign in to MCP servers with OAuth - #106

Merged
sanchitrk merged 52 commits into
canaryfrom
claude/mcp-oauth-65afa7
Oct 30, 2026
Merged

sanchitrk merged 52 commits into
canaryfrom
claude/mcp-oauth-65afa7

Conversation

@sanchitrk

Copy link
Copy Markdown
Contributor

Summary

Stacked on #83. Streamable HTTP MCP servers can now sign in with OAuth, or send a model provider's credential as the bearer. The SDK (@modelcontextprotocol/client 2.3.1) runs discovery, dynamic client registration, PKCE, the code exchange and refresh. This PR keeps the credentials and decides when each step happens.

Credentials

  • Stored in <home>/mcpauth.json (mode 0600), keyed by server name and URL, so the same URL under two names signs in separately.
  • Each write takes a lock on the file, re-reads it, changes one entry, then writes a temp file and renames it into place.
  • Servers rotate refresh tokens, so a refresh holds a per-server lock across processes from reading the tokens to saving the new ones. Within one process, concurrent 401s share one refresh. Tokens another process already refreshed are used without refreshing.
  • token() reads the store before every request, so a sign-in or refresh by any process applies at once.

Connections never open a browser

  • A server with no Authorization header and no auth gets an OAuth auth provider. With no stored tokens it sends no header, so open servers are unaffected.
  • A token within 30 s of expiry is refreshed before it is sent; a 401 triggers a refresh. When neither works, the server is needs-auth. A call to it tells the model: MCP server "x" requires sign-in. Run "codework mcp login x".
  • A 403 insufficient_scope also means sign-in is needed. The challenge is stored, and the next sign-in requests the missing scope on top of the scope already granted.
  • Once the stored credential changes, the next exchange reconnects a needs-auth server and waits for it.

Signing in: codework mcp login <name> / codework mcp logout <name>

  • Login connects first: when the server already accepts the stored tokens it says so and opens no browser, and its 401 challenge tells the sign-in where the metadata is and which scope to ask for. Then it opens the authorization page (--browser=false only prints the URL) and waits for the loopback callback on 127.0.0.1. A redirect URL pasted into the terminal also works, for SSH sessions.
  • --timeout limits the whole sign-in (default 300 s). Ctrl+C cancels it at any step; refreshes are never cancelled.
  • A registered client's redirect port is reused when it is free. Optional oauth settings: clientId, clientSecret, callbackUrl / callbackPort (loopback only), scope, clientName, authServerMetadataUrl.
  • The list command and the /mcp view come in a later PR.

auth: { provider }

  • Sends the provider's credential as the bearer: its OAuth login token, else its API key from the environment. This is the same lookup model calls use, now shared in ModelCatalog.providerToken.
  • It is read on every request, and MCP keeps no copy.
  • Only allowed in the user mcp.json, and only for https URLs or loopback hosts.

Fixes on top of the SDK

  • Only http / https URLs are fetched or opened, so a file: authorization endpoint can't launch a local program.
  • null and "" fields in authorization-server JSON are treated as absent. The SDK's schemas reject them, and real servers send them.
  • Well-known metadata is fetched without the server URL's query.
  • A callback carrying iss when no authorization-server metadata was discovered is rejected (RFC 9207).
  • Every request to the authorization server times out after 15 s.
  • Checked and left to the SDK: native application_type for loopback redirects, prompt=consent with offline_access, and the iss check when metadata exists.

Also

  • proper-lockfile now backs one Effect lock helper (util/lock.ts). The plugin store and settings locks use it too, in place of their own mkdir lock.
  • The aikit OAuth result pages are exported from @codeworksh/aikit/oauth/interactive and shared with the codex login.
  • Client registration presents the app: client_name "CodeWork", client_uri https://codework.sh, and logo_uri pointing to a new 256 px icon, sites/www/public/brand/icon.png (57 KB, cut from 3d.png, which is 1.4 MB). Consent pages such as Linear's show these. The icon appears once the site is deployed with the new file.
  • Docs: a "Signing In" section on the MCP page.

Test plan

packages/codework/test/cli.mcp.oauth.test.ts runs the real CLI against a fixture that is both an MCP server and its own authorization server: protected-resource and authorization-server metadata, DCR, PKCE, rotating refresh tokens, and null / "" fields. The cases follow the reference agents' OAuth tests.

  • Main flow (cli.mcp.oauth.json):
    • Before sign-in the OAuth server declares no tools and no client is registered. A server with auth.provider sends the provider's API key.
    • codework mcp login registers a native client, verifies PKCE, stores the tokens with mode 0600, and the callback page reports success. A second login says it is already signed in and opens no browser.
    • The same URL under a second name stays signed out.
    • Two codework run processes that find the same token rejected share one refresh grant, through the lock across processes.
    • An access token that expires mid-run is refreshed once for two parallel calls.
    • With every token revoked, the call tells the model how to sign in again. Logout removes the entry.
  • Step-up (cli.mcp.oauth.scope.json): a 403 insufficient_scope asks for sign-in and stores the challenge. The next login signs in through the browser, without trying a refresh, for tools admin, and the call then works.
  • What a sign-in trusts (cli.mcp.oauth.cases.json):
    • Accepted: configured authServerMetadataUrl; iss from the right issuer (as Linear sends it).
    • Refused, with nothing stored: metadata naming another issuer; a file: authorization endpoint; iss with no metadata to check it against; iss from another server; a rejected code.
    • An interrupted login stores nothing, and the callback port is closed.
  • CLI refusals (cli.mcp.oauth.refused.json): unknown server, stdio server, auth.provider server, own Authorization header, for both login and logout.
  • Every artifact matched across three reruns. Requests whose order depends on the background SSE stream are kept out of the logs.
  • mcp.session.test.ts now checks two new config errors: a non-loopback callbackUrl, and auth in a project file. The lifecycle artifact drops the background GET, whose position varies.
  • Not covered end to end: pasting the redirect URL, which needs a terminal for stdin.
  • vp check and vp run typecheck pass. Harness: 570 passed, 34 skipped. Codework: 120 passed, 24 skipped; tui.test.ts "stops a server whose registration another server took over" fails here only because another worktree's test server holds its fixed port 7610. Aikit: 284 passed.

🤖 Generated with Claude Code

sanchitrk and others added 27 commits October 24, 2026 19:09
Connect to one MCP server over stdio or Streamable HTTP through the
official SDK. Stdio servers run on the host in their own process group
and are stopped with the group; HTTP connects retry transient failures.
List pages and tool results are validated by the SDK.

The process-group stop sequence moves out of the host shell into a
shared Process.terminate helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Connections pass the server's notifications/message entries to an
onLog handler, and McpLog appends them to a file with one line per
entry, rotating it past 5 MB.

A result that fails the SDK's schema is reported on one line as
`Invalid result for <method>: <path>: <message>` instead of the
validator's multi-line issue list, which is still logged at debug level.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Name the MCP entry points with Effect.fn and give each request its own
span. A server without resource templates is now recovered from inside
the Effect rather than on the SDK promise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Count stderr as an open pipe, so a descendant holding only stderr is
  still killed with the server's process group.
- Bound the whole connect attempt by the startup timeout; the SDK only
  times the initialize request, not the initialized notification.
- End the HTTP session a failed connect attempt was given, through a
  fresh transport, since the SDK aborts the failed transport's signal.

Tests now cover these, retries of reads but not tool calls, session
termination and 400 classification, and register their own teardown
for spawned processes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The process spawner kills the group when the connection's scope closes,
which hid a missing kill. Assert instead that a grandchild holding only
stderr is gone once the connection reports the server's exit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…shutdown

- Retry connects only on HTTP 408/429/5xx and fetch failures with a system code;
  any other TypeError, such as an invalid header value, fails once.
- Retry list and read requests once, 250 ms later, after a transient HTTP error.
- Bound startup by the request timeout unless set on its own.
- Ask for progress only on requests given a progress handler.
- SIGTERM a stdio server's process group even after the server exits on its own,
  and before SIGKILL when the leader is gone but a pipe is still open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The log handler is now a connect option instead of a setter called after the first tool
listing, so messages a server sends while starting, or before failing to, are kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A tools/list_changed sent while the first listing is answered used to reach no handler,
leaving the old list in place; it is now reported once the handler is set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reads mcp.json from the user and project layers, keeps each session's
servers connected across exchanges, and declares their tools to the model.

- mcp.json: project entries replace user ones or override only enabled,
  exposure and toolExposure; broken files and entries are reported and
  skipped. env and headers resolve ${VAR} and !command values.
- Plugins get a ctx.plugin.mcp bucket in a new mcp domain that runs first;
  it is settled before the tool domain, so tool plugins see MCP tools.
- Tool definitions are frozen per exchange; each call uses the server's
  current connection. A dropped connection reconnects on the next call, an
  expired HTTP session is replaced and the call retried once, tool calls
  are never retried otherwise.
- Tools are named mcp__<server>__<tool> with a hash suffix on collisions;
  exposure is direct or hidden.
- Tool.fromJsonSchema sends a server's JSON Schema to the provider as
  written and validates arguments against its Effect translation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A server's own relative cwd now resolves against the session's base
directory, and a leading ~/ is expanded in command, args and cwd.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tled

- Connection callbacks run in the service's scope. A server exiting while
  idle used to retire its connection from inside the connection's own
  scope, which waited on itself and left the server locked for good.
- Connect attempts run on their own and are shared by callers; closing a
  server interrupts one in progress instead of waiting behind it.
- An exchange waits up to 10 s for every server it starts, not only on
  the first exchange, so a restarted server keeps its tools declared.
- Server configs in ctx.plugin.mcp are copied and deep-frozen, so a
  plugin cannot change a settled server afterwards.
- A hashed tool name grows until it is free, so a server tool named like
  the hash cannot replace another tool.
- Server log messages go to <home>/mcp.log.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Refuse env and header values with a line break or NUL without quoting them.
- Run a !command with stdin closed, and reuse its output for the life of the process.
- Report auth/oauth entries as unsupported instead of ignoring the keys.
- Drop the nulls strict sampling writes for omitted optional arguments before the call.
- Validate JSON Schema patterns instead of skipping the whole schema.
- Refresh a changed tool list without holding the server lock.
- Retry a server whose connect failed at the next exchange, in the background.
- Stop removed or changed servers without making the prompt wait.
- Keep hashed tool names within 64 characters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…aces

- Start a connect attempt after it is recorded, so one that fails at once (an unset
  variable, say) no longer blocks every later retry.
- Close server connections in parallel on shutdown, after interrupting connect attempts.
- Keep only the latest tool listing when list_changed notifications overlap.
- Write server log messages from the handshake on.
- Kill a !command that ignores SIGTERM, and share one run between concurrent connects.
- Allow line breaks in env values (a PEM key); headers still refuse them.
- Reject arguments a closed JSON Schema object does not declare, instead of passing them on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Write server log messages on the service's fibers, so a failed handshake closing the
  connection no longer drops the messages that explain it.
- Forget a failed !command as soon as it fails, so the next connect runs it again even
  when every caller waiting on it gave up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e host

- list_mcp_resources, list_mcp_resource_templates and read_mcp_resource
  reach every enabled server with resources, through the same request
  path as tool calls (reconnect, expired-session recovery, sign-in).
  Listings page per server or cover every page; MCP App resources are
  left out.
- Results keep the start and end of text over 20 KB and save the full
  text; binary resources are saved, text-typed blobs shown as text, and
  resource links name read_mcp_resource.
- Saved files go to the host temp directory (mode 0600), since MCP runs
  on the host whatever sandbox a session uses.
- Docs: an MCP page under Customize.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Listing every server's resources or templates uses the SDK's own
  pagination and its limits, so a server repeating a cursor cannot keep
  a listing running.
- A cursor goes back to the server exactly as it was given; only server
  names and URIs are trimmed.
- Tests remove the files they save, and read saved paths between the
  message's own delimiters.
- Docs: which servers a message waits for, exposure changes keep a
  server running, and where server logs go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…g servers

- A blank cursor lists the first page; any other cursor goes back exactly as given.
- Resource tools wait for servers still connecting, so none is left out of a listing.
- Resource failures carry the server's own message; listings name the server beside it.
- Docs: where stdio servers start off a local sandbox, $NAME values, command caching,
  sign-in, and retries after a failed connect.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tool and resource images are converted to a format providers take inline and resized to
their limits, as the read tool does; one that cannot be becomes a note instead of an image
that would fail the next request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A server's scope decides who shares a running instance: session (the
  default), space (sessions in one space) or app (every session). An
  instance is keyed by its scope and everything its connection is made
  from, so sessions resolving different settings never share one.
- Exposure stays each session's own; sessions sharing an instance can
  declare different tools.
- Each drain leases its session's instances. An instance no session uses
  closes at once; one no drain holds closes after an idle timeout
  (10 minutes, Harness option mcpIdleTimeout).
- space servers start in the space's folder and are sent it as root on a
  local sandbox; app servers start where the app started, with no roots.
- A session's servers keep their config order across exchanges, so a
  restarted server no longer moves its tools to the end.
- Docs: sharing a server, and idle close.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… interrupts

- An instance key includes the server's name, so two entries with the same
  settings are two instances and a renamed server never closes the
  instance its new name uses.
- Leases count each instance once per session, so an alias can no longer
  drive a count negative and keep a server from idling out.
- Reconcile updates every membership and lease count in one step and
  closes unused instances on their own, so an interrupted exchange cannot
  leave a shared instance holding a session it no longer has.
- An instance that starts with no drain holding it still gets an idle
  timer.
- Keys are canonical JSON, so the same env or headers in another order
  share an instance.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every MCP failure is a Schema.TaggedError with the message the model
reads, turned into a tool result only at the edge:

- UnavailableError: disabled, shut down, not connected, needs sign-in,
  or a tool no longer offered.
- ToolCallError: a tool call or resource request failed on the server.
- ResourceError: unusable resource-tool arguments, or a server without
  resources.
- ValueError: an env or headers value that does not resolve.
- OutputError: output that could not be saved.

Connect attempts fail with ConnectError. The text the model sees is
unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
codework run reads mcp.json next to the user settings, starts a stdio MCP
server written against the wire protocol, declares its tool to a fake
OpenAI-compatible provider with the server's schema, returns the call's
result to the model, and stops the server when the CLI exits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mcp.json accepts every exposure Pi does: direct, hidden, codemode and
deferred, with codemode-deferred read as codemode, so entries copied
from Pi stay valid. Until codemode and tool_search exist, codemode and
deferred tools are not declared and a session is warned once that they
cannot be reached. Resource tools are declared when a server with
resources is direct, and reach every server with resources that is not
hidden.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ks reachable

- Restart an instance whose connect failed at the next exchange, so shared space/app
  instances recover for every session using them.
- Carry earlier fixes onto the scoped service: tool-list refresh without the server
  lock, plain resource failures, and resource tools waiting for connecting servers.
- Point resource links to read_mcp_resource only when that tool is declared.
- Drop the record of a session with no MCP servers once its drain ends.
- Hold a lease across the scope test's runs so a slow runner cannot change its pids.
- Docs: app servers get no roots.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The scoped service gets the fixes from the session runtime: attempts recorded before they
start, connections closed in parallel after attempts are interrupted, the latest tool
listing kept, server log messages from the handshake on, and header/env value checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Server log messages are written on the service's fibers here too, so a failed handshake
no longer drops the messages that explain it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Streamable HTTP MCP servers without an Authorization header sign in with
OAuth. The SDK runs discovery, client registration, PKCE, the code
exchange and refresh; the harness keeps the credentials and decides when
each step happens.

- Credentials live in <home>/mcpauth.json (0600), keyed by server name
  and URL. Writes take a file lock; a refresh holds a per-server lock
  across processes, and concurrent 401s in one process share it.
- Connections never open a browser: they refresh, or tell the model to
  run `codework mcp login <name>`. A 403 insufficient_scope is stored so
  the next sign-in asks for the missing scope. A server that needed
  sign-in reconnects once its credential changes.
- `codework mcp login` connects first, then runs the browser flow against
  a loopback callback or a pasted redirect URL; `codework mcp logout`
  removes the entry.
- `auth: { provider }` sends a model provider's login token or API key
  as the bearer, read on every request; user mcp.json only, https or
  loopback only.
- On top of the SDK: http(s)-only URLs, null and "" fields treated as
  absent, no query on well-known metadata URLs, an iss without
  discovered metadata rejected, 15 s per authorization-server request.
- The client registers as CodeWork with the app icon.
- One Effect lock helper on proper-lockfile replaces the plugin store's
  own lock; aikit exports the OAuth result pages for both logins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
sanchitrk and others added 2 commits October 30, 2026 12:41
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
sanchitrk and others added 22 commits October 30, 2026 12:49
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each thread now owns its MCP servers: reconcile, status and the new
connect and disconnect take the thread, so concurrent threads of one
session, or threads at different placements, no longer overwrite each
other. A thread's record is dropped once it has no servers left.

A failed server is no longer retried by every turn; it recovers through
a config change or an explicit connect. Disconnect closes a server and
keeps it closed until connect or a config change. A dropped connection
still reconnects on the next call.

Every tool a server offers is registered with its exposure, so deferred
tools are found by toolsearch, codemode and hidden ones are registered
but not offered. mcp.json accepts codemode and deferred exposure, with
codemode-deferred read as codemode. A loaded deferred tool makes the
turn wait for its server like a direct one.

State changes are published as the ephemeral mcp.server.status event to
the owning thread, and the needs-auth state is now authenticate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Connect and disconnect run one at a time per server and return the
status read under that lock; a server a turn replaced meanwhile is
reported unknown. Stopping reads and interrupts the connect attempt
under the server lock, and an attempt that finishes after its server
was closed or disconnected closes its connection instead of installing
it. An explicit connect always publishes a fresh connecting status.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resource tools reach the thread's servers, skip disconnected ones, and
stay declared to the model. Sign-in failures on resource requests set
the authenticate state through the status event.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Shared instances now serve threads: a session-scope instance is keyed
by session plus the thread's cwd and roots, so threads at the same
place share it and a thread placed elsewhere gets its own. Instance
users and leases count threads, and lease takes the thread. Status
events go to every thread using an instance; a thread that starts
using a running instance gets its current status, and a disabled entry
reports disabled to its thread. Connect and disconnect act on the
instance behind the thread's server.

Reconcile no longer restarts failed shared instances. Every tool is
registered with its exposure, the unreachable warning covers codemode
only, and UnknownServerError joins the tagged MCP errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The sign-in paths set the authenticate state through the status event,
and reconnecting an instance whose stored credential changed is the
only automatic reconnect left; it now runs for the threads using that
instance and publishes connecting, then the outcome.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ifact

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rted errors

An instance that idles out publishes disconnected to the threads still
using it. A thread record with reported config errors is kept, so they
are not logged again every turn. A new instance is started on the flag
set when it was created, and a thread joining a running instance is
told its status only if nothing newer was published since it joined.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The sign-in check reads credentials only for the instances the
thread's servers resolve to, and a restarted signed-in instance
follows the created and joined bookkeeping.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…upted attempts by state

Deleting a session now forgets its threads' MCP records and closes their
servers. A caller waiting on a connect attempt that was interrupted is told
whether the server was shut down, disconnected or is reconnecting, and
connect-time close reasons read like the ones after connect.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Connect on an instance that idled out ran into a shut-down server and
reported it disconnected with no error. It now says the instance closed
while idle and that the thread's next message starts it again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… a new credential

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sanchitrk
sanchitrk changed the base branch from claude/mcp-scopes to canary October 30, 2026 14:09
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sanchitrk
sanchitrk merged commit a0fae1d into canary Oct 30, 2026
2 checks passed
@sanchitrk
sanchitrk deleted the claude/mcp-oauth-65afa7 branch October 30, 2026 14:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant