Connect an agent

At the end of this guide, an MCP client can search and file the catalog through /mcp. You need a running uris that is connected to masks, and an account in the masks tenant it signs in with.

Allow dynamic registration in masks

An MCP client registers itself with masks the first time it connects. The masks tenant has to allow that.

1. Open the masks tenant’s settings.
2. Under Dynamic registration, choose On, or On, limited to these scopes.
3. If you limit it, list openid, profile, email, offline_access, and every scope in the table below. A client asks for every scope uris offers, and masks refuses the whole request with invalid_scope when one of them is beyond the limit.

MASKS_DYNAMIC_REGISTRATION on the masks deployment overrides the tenant’s choice. See registering a client in the masks docs.

Claude Code

1. Add the server. Use your uris address followed by /mcp:

   claude mcp add --transport http uris http://uris.localhost:8180/mcp

2. Start claude and run /mcp. Choose uris, then authenticate.

3. The browser opens masks. Sign in, and approve the scopes the client asks for.

4. Back in Claude Code, /mcp lists uris as connected, with its tools.

Claude and other clients

Any MCP client that speaks OAuth and registers itself dynamically can connect. Give it the /mcp URL, such as https://uris.example.com/mcp. The address without /mcp answers 404, and the resource the metadata names is the /mcp URL, which a client checks against the address it was given.

In Claude, open Settings → Connectors, choose Add custom connector, and enter a name and the /mcp URL. Claude sends you to masks to sign in and approve, and then lists the uris tools under the connector, where you choose which ones it may call without asking.

Note

Claude Desktop reaches a custom connector from Anthropic’s servers, so the address has to be public. uris.localhost works only for a client running on the same machine, such as Claude Code.

What the client does

You do not configure any of this. It is listed so you can follow it in a log.

1. The client calls /mcp without a token. uris answers 401 with a WWW-Authenticate header that names /.well-known/oauth-protected-resource.
2. The client reads that document. It lists the /mcp URL as the resource, the masks issuer as the authorization server, and every uris: scope an MCP tool checks, with its description.
3. The client registers with masks and sends you there to sign in and approve.
4. The client calls /mcp again with the token masks issued.

See agents and MCP for how the endpoint is built.

Choose the scopes

The tools a client sees depend on the scopes its token holds. A tool the token does not reach is left out of tools/list.

Scope	What it unlocks
uris:catalog:read	search, and feed to read a feed
uris:catalog:write	connect, and feed to note, rename, analyze, create, place, or change a lifetime
uris:resources:read	resource, to list resources and ask them read-only commands
uris:resources:command	resource commands that act: check, sync, keep, export, cancel, put, and snapshot
uris:web:read	resource searches on a web search resource
uris:web:keep	resource snapshot on a web resource, without uris:resources:command
uris:mcp:call	the tools of every MCP server attached as a resource

uris offers each of these scopes, and a client asks for all of them. A masks limit narrower than this table refuses every such client, so limit a client in the client instead, such as Claude’s per-tool permissions. The full list is in the scopes reference, and each tool’s arguments are in the MCP reference.

Check that it works

Ask the agent to search the catalog for a word you know is in it. It calls search and returns feeds with their ids. Then ask it to list resources, which calls resource with no key.

If it does not connect

The masks log shows each step the client took.

What you see	Why
The client never opens masks	The masks metadata at /.well-known/oauth-authorization-server has no registration_endpoint, so dynamic registration is off.
masks redirects back with invalid_scope and this client may not request	The tenant’s limit leaves out a scope uris offers. Add the scopes it names.
The client gets 404	The address is missing /mcp.

If it doesn’t work

• The client never opens masks. Dynamic registration is off in the masks tenant.
• 401 after signing in. uris refused the token, for example because masks issued it for a different tenant. uris records each refusal with its reason on the Activity page in Settings.
• 503 from /mcp or /.well-known/oauth-protected-resource. masks is not answering, or MASKS_ISSUER_TEMPLATE is not set. The response body says which.
• A tool is missing. The token does not hold the scope for it. Authenticate again and approve the scope.
• 429 too many requests. The token made more than URIS_MCP_LIMIT calls in a minute, 120 by default. See the environment reference.