Browsing & Connecting

Discover MCP servers and set up connections.

Browse Available Servers

1# List all servers2belt mcp list34# Filter by category5belt mcp list --category developer6belt mcp list --category productivity78# Show only featured servers9belt mcp list --featured1011# Search by name or description12belt mcp search "slack"13belt mcp search "issue tracking"

Output shows slug, category, auth type, connection status, and description:

1mcp servers2slug         category      auth    status       description3linear       developer     oauth   connected    Project management and issue tracking4slack        communication oauth   —            Team messaging and notifications5github       developer     oauth   —            Code hosting and collaboration

Get Server Details

1belt mcp get linear

1Linear23Project management and issue tracking45  slug         linear6  category     developer7  auth         oauth8  server       https://mcp.linear.app9  docs         https://linear.app/docs/mcp10  status       connected1112  tools: belt mcp tools linear

Refresh server metadata

Re-probe an MCP server to update its name, description, auth type, and logo. Useful after a server adds PRM metadata or when initial enrichment returned hostname-style names:

1belt mcp refresh todoist2belt mcp refresh clickup

1Refreshed Todoist2  Task and project management3  auth: oauth4  icon: https://...

The CLI resolves the slug to a server ID and calls POST /mcp-servers/{id}/refresh. Requires belt login.

Connect

When you connect with a bare origin URL (for example https://mcp.example.com), the platform resolves the actual MCP endpoint before OAuth:

1. Server card — GET /.well-known/mcp-server-card (MCP remote discovery)
2. UCP — GET /.well-known/ucp when the server advertises an MCP transport (Universal Commerce Protocol)

You can paste either the origin or the full MCP URL. The web app and API use the same resolution when you provide server_url in a connect request.

OAuth Servers

Most connectors use OAuth. The CLI opens your browser to authorize:

1belt mcp connect linear

1Authorize Linear:23https://linear.app/oauth/authorize?client_id=...&scope=...45Waiting for authorization...67Connected to Linear8  tools: belt mcp tools linear

The flow:

1. CLI opens your browser to the service's authorization page
2. You approve the requested permissions
3. Tokens are exchanged and stored encrypted in your workspace
4. CLI confirms the connection

For servers that support Client ID Metadata Document (CIMD) OAuth, inference shell identifies itself via https://app.inference.sh/.well-known/mcp-client.json (see MCP OAuth client identity) instead of registering a new OAuth client on each connect. Servers without CIMD support fall back to Dynamic Client Registration or BYOK credentials you provide.

Microsoft Entra ID (Azure DevOps and similar): Entra does not offer CIMD or dynamic registration. Connect through an OAuth app registered for the MCP server's host (GET /credentials/mcp/app shows whether one is needed, optional tenant_id for single-tenant apps, and an admin consent link). A tenant admin approves the app once; members then connect with their own accounts. If the redirect returns without an authorization code, the callback page calls POST /oauth-callback/notice to show the error or approval message. → Credentials API — Configure MCP OAuth app

Non-interactive OAuth (CI, scripts): When stderr is not a TTY, CI is set, or BELT_NON_INTERACTIVE=1, belt mcp connect prints the authorization URL but does not open a browser or poll for completion. Open the URL manually, approve access, then verify with belt mcp get <slug> or belt credentials list.

When you connect a custom MCP server URL (not a pre-registered slug), the API resolves the endpoint before OAuth:

1. Server Card (SEP-2127) — if the URL is a bare origin (e.g. https://mcp.example.com), GET /.well-known/mcp-server-card may redirect to the real MCP endpoint.
2. UCP discovery — if still a bare origin, GET /.well-known/ucp is checked for a transport with "transport": "mcp" and an endpoint URL (Universal Commerce Protocol merchants).

You do not need to discover endpoints manually; pass the merchant or vendor origin and the platform follows redirects to the MCP URL.

REST discovery proxy (for custom UIs; avoids browser CORS on redirects):

1GET https://api.inference.sh/mcps/discover?url=https://mcp.example.com

No API key required. The API tries /.well-known/mcp-server-card, then OAuth metadata on the URL. Returns the server card or OAuth discovery JSON with Cache-Control: public, max-age=300. Use the same URL shapes as when connecting via CLI or the web app.

→ MCP Servers REST API: full directory, workspace CRUD, and tool proxy reference

API Key Servers

Some servers use API keys or personal access tokens instead of OAuth. In the web app, enter the token when connecting a custom MCP server. The token is stored as an encrypted workspace secret and sent as Authorization: Bearer on tool calls.

For programmatic connect, pass the token in POST /credentials metadata as bearer_token (see Credentials API — Bearer token connect).

No-Auth Servers

Public servers that don't require credentials connect immediately.

Custom MCP servers

The directory covers known servers (belt mcp connect linear). Custom servers use a two-step flow in the web app (/my/mcps):

1. Add — register the server URL and choose who can see it: your workspace (team) or everyone (public, directory listing). Adding never shares your login. On save the platform probes the server and sets up its sign-in from what the server publishes (OAuth metadata, an API key, or no auth), and declares the vault credential the server uses. When discovery cannot build a provider, set the credential in the edit dialog (or fix the URL) before anyone connects.
2. Connect — authorize your account from the server row (or right after adding). Choose who can use your connection (only you by default for MCP).

The sharing control on each row changes visibility and connection scope independently. Vault credentials entries for MCP link to the server page, not the generic OAuth credential list.

You can also browse Explore → MCP servers (/mcps), call POST /mcp-servers, or connect with POST /credentials and provider: "mcp" plus metadata.server_url. From vaults → credentials, add credential → MCP server opens the same add dialog on /my/mcps?add=1.

When server_url is a bare origin (scheme + host, path / or empty), the API resolves the actual MCP endpoint before OAuth:

1. MCP server card — GET /.well-known/mcp-server-card (SEP-2127); uses the first remotes[].url when present.
2. UCP discovery — GET /.well-known/ucp; uses the first service transport with "transport": "mcp" and a non-empty endpoint.

If discovery fails, the original URL is used. Paste the full MCP path when you already know it (for example https://mcp.linear.app).

Entra ID and servers without dynamic registration

Some remote MCP servers (notably Azure DevOps MCP on dev.azure.com) sign in through Microsoft Entra ID and do not support Dynamic Client Registration. Before members can connect, a workspace, org, or platform admin registers an Entra application with PUT /credentials/mcp/app. Entra admins may need the one-time admin consent URL from GET /credentials/mcp/app (admin_consent_url). See Credentials API — MCP OAuth app.

Admins can set the same app from the web app: the sign in tab of the connect dialog offers set up OAuth by hand (client id, secret, endpoints), and the server's edit dialog has an OAuth app section. Once saved, the app also shows under the server in the vault's credentials tab.

MCP servers and the vault

An MCP server is a consumer of a credential, like an app: it declares the credential slug it needs (credentials on the server) and then signs in through the vault. Add sets that declaration from discovery; change it in the edit dialog's credential section, or pass credentials on POST/PUT /mcp-servers. Each slug must name a real provider (a catalog slug, your team's auth scheme, or <server-slug>-mcp). A slug that names nothing is refused when you save the server, with a message naming it; leave credentials empty to set up sign-in from the server instead. Its token is minted for the server itself, so a company's API and its MCP server are two credential slugs (abc and abc-mcp); an abc login never satisfies abc-mcp.

For a server that declares a credential:

• the row and the server page say signs in with <slug>, linking to the vault entry;
• connect starts that provider's sign-in (the same as connecting it from the vault); disconnect removes that login;
• its connection status and its tool calls use your login for that slug; a server-specific MCP login is no longer created.

Saving a server's OAuth app by hand with both endpoints (see below) registers an auth provider named <server-slug>-mcp, declares it on your registration, and the server appears in the vault under that slug. Servers that declare nothing keep the MCP-specific connect flow described above; their OAuth app is still listed in the vault's credentials tab, so an app that is set up but not yet connected is visible there with a connect button.

When sign-in discovery fails

Connecting an OAuth server starts by asking it how it signs in (its protected resource and authorization server metadata). Some servers don't publish that metadata, and some URLs aren't MCP endpoints at all, for example a vendor's settings page. Connect then fails with a message saying which, instead of a generic error:

• did not answer as an MCP server with OAuth sign-in: the URL answered, but not as an MCP server. Check you pasted the MCP endpoint, not a web page. If the server takes an API key, use the token tab instead.
• could not reach: the URL didn't answer. Check it.
• did not publish usable OAuth metadata: the server names a sign-in server, but that one's metadata is missing or incomplete.

If the server does use OAuth and you have its details from the vendor's docs, set up its OAuth app by hand. A workspace admin (or org admin) does this once, then everyone connects without entering anything:

1. Open the server's connect dialog. When we couldn't discover how it signs in, the sign in tab shows the OAuth app form straight away. Otherwise use set up OAuth by hand, or the OAuth app section of the server's edit dialog.
2. In the vendor's developer console, create an OAuth app and add the redirect URI the form shows.
3. Enter the client id and client secret, then the authorize URL and token URL from the vendor's OAuth docs, and the scopes if the vendor needs them.
4. save app, then connect.

With both URLs set, connecting skips discovery and goes straight to them. Leave both empty to go back to discovery. The same app is available through the API: Credentials API: endpoints by hand.

The server URL still has to be an MCP endpoint, since tools are listed and called there. A vendor that offers only a REST API, or an MCP server that runs only on your own machine, can't be connected this way.

Optional static headers on the MCP server registration (for example X-MCP-Toolsets, X-MCP-Readonly) limit which tools the remote server exposes. Set them with POST /mcp-servers or PUT /mcp-servers/{id} — see MCP Servers API.

Check Connection Status

Connection status is shown in belt mcp list and belt mcp get:

To list every credential your workspace has connected (OAuth, service accounts, and MCP):

1belt credentials list

1provider                       type       source   status       display name2google                         oauth      own      connected    My Workspace3mcp                            mcp        own      connected    Linear

Inspect one connection (including scopes and account identifier):

1belt credentials get google2belt credentials get mcp --json

Use --json when you need the credential id for agent connector tools.

Disconnect

Revoke a connection and delete stored credentials. Requires belt login (or INFERENCE_API_KEY):

1belt mcp disconnect slack

1Disconnected from Slack

Next

• Using Tools — call tools on connected servers
• Agent Tools — add connector tools to your agents