Developers: Tokens & MCP

Who this is for

Anyone calling an app behind someone’s Agent address from a program, an AI client or another Agent. If you just want to use your own computer from your phone, start with Use Your Home Agent Anywhere.

Terms used on this page: handle (the first label of the address), service (an app the owner registered — a local port on their computer), and host (the computer running the UUMit desktop app).

Address layout

Purpose	Form
Address home page	https://<handle>.agent.example/
Path-style service	https://<handle>.agent.example/s/<service>/
Dedicated-host service	https://<service>--<handle>.agent.example/
Agent Card	https://<handle>.agent.example/.well-known/agent-card.json
Signing keys	https://agent.example/.well-known/jwks.json

For Mainland, use agent-cn.example instead. The two editions have separate accounts and data. The Agent Card is signed by the platform; verify it against the JWKS before trusting the capabilities it lists.

Credentials

Credential	How to send it	Typical use
Browser session	Cookie (sent automatically after signing in to UUMit)	Browsers
Personal access token (PAT)	Authorization: Bearer pat_…	Scripts, automation
Platform API key	X-Api-Key + X-Platform-User-Id	Third-party Agents on the platform
OAuth access token	Authorization: Bearer … (from the consent page)	MCP clients
Short-lived access token	Authorization: Bearer aat_…, valid for one service only	Native clients

The gateway validates these and strips them before forwarding to the host, so apps on the host never see your UUMit credentials. Whether a caller may use a service depends on the owner’s “Who can use it” setting and grants.

MCP clients

Note

MCP authorization opens at the end of P1, behind the feature_flag.agent_address_mcp_oauth flag; until then it returns FEATURE_REQUIRED.

1. Add the service’s MCP URL (path-style or dedicated host, plus the app’s own MCP path) to your client.

2. On 401, the client follows resource_metadata in the WWW-Authenticate header to discover the authorization server and registers (metadata document or dynamic registration).

3. The browser opens the UUMit consent page. Once the owner or a grantee approves, the client receives an access token valid for that one service.

4. Consent can be revoked any time under “Who can use my stuff”; tokens stop working immediately.

Native clients

Short-lived token

uumit-connector access login            # first time: save a PAT
uumit-connector access token alice/notes
# prints Bearer aat_…, valid for 15 minutes; --raw prints only the token

OpenClaw remote

uumit-connector openclaw remote alice

Writes gateway.remote.url and edgeAuth into the OpenClaw config (backing it up first). OpenClaw then fetches a short-lived token on each connection.

Local forward

For clients that can’t send custom headers, forward the service to a local port:

uumit-connector access alice/notes --listen 127.0.0.1:8080

TCP / SSH

uumit-connector access alice/ssh --listen 127.0.0.1:2222

Or in ~/.ssh/config:

Host alice-ssh
  ProxyCommand uumit-connector access alice/ssh --stdio

SSH-type services require step-up by default.

Step-up

Services with “Confirm it’s you on your phone” turned on may return STEP_UP_REQUIRED with a challenge_id. The caller should:

1. ask the user to confirm on their phone;
2. poll GET /api/v1/agent-address/step-up/challenges/{challenge_id} until it is approved or expires;
3. retry the same request once approved.

uumit-connector access token waits for confirmation by default (--wait-step-up seconds; 0 means don’t wait).

Errors and retries

• Error responses carry a stable code. Branch on code, never on the message text.
• 4xx means a caller problem — don’t retry. 5xx can be retried with backoff.
• On 429, back off for the number of seconds in Retry-After.
• When retrying non-idempotent requests, send the same Idempotency-Key. The gateway passes it through to the host for the app to de-duplicate.
• Host offline or app not responding returns a 502 / 504-class error — retry later. ROUTE_NOT_FOUND means the address or service doesn’t exist — don’t retry.

Full list in Errors & Rate Limiting.

Skill and CLI

• UUMit skills (uumit-shared / uumit-publish): shipped with the desktop client; let Claude Code, Codex and OpenClaw publish apps and invite people through the local uumit-connector command line. Before making something open to everyone they confirm in the chat (uumit-connector skills read uumit-publish shows the full text).
• npx @uumit-ai/uumit share <port>: share a page with one command.
• npx @uumit-ai/uumit address status: see who can use each service on the account.