Connect Claude.ai / Gemini to a Vetrix MCP server over OAuth

This guide is for end users who want to point an AI assistant — such as a Claude.ai custom connector or the Gemini CLI — at a Vetrix repository's MCP server so the assistant can read repository data on your behalf.

Vetrix exposes one MCP (Model Context Protocol) server per repository at:

https://<host>/api/v1/mcp/<owner>/<repo>

Replace <host> with your Vetrix instance host, and <owner>/<repo> with the repository you want the assistant to read. You can copy the exact URL from the repository's Settings → MCP page in the Vetrix web UI.

The server authenticates the assistant with OAuth 2.1 and grants it the read-only mcp:read scope. There are two ways to get connected:

Zero-config path — if your instance administrator has enabled Dynamic Client Registration (DCR), the assistant registers itself automatically. You just paste the server URL and approve a consent prompt. Start here.
Manual path — if DCR is disabled, you register an OAuth app yourself at /settings/applications and paste its Client ID into the connector. This works for clients that use a loopback redirect (such as gemini-cli); the Claude.ai connector requires DCR and cannot use the manual path (see Troubleshooting).

Read-only scope. mcp:read only lets the assistant read the repository (and only repositories you can already see). It cannot push, merge, change settings, or act on anything your own account cannot already access. Scope is additive on top of your existing permissions.

1. Before you start

You need:

A Vetrix account that can already see the repository you want to connect.
The repository's MCP server URL — copy it from Settings → MCP on the repository, or build it as https://<host>/api/v1/mcp/<owner>/<repo>.
An AI assistant that speaks MCP over OAuth, for example:
- Claude.ai — a custom connector (requires DCR; see below).
- Gemini CLI — an MCP server entry (works with DCR or the manual path).

Which path you use depends on whether your administrator has enabled DCR on the instance. If you are not sure, try the zero-config path first — if DCR is off, the assistant will tell you that automatic registration is not supported, and you can fall back to the manual path (where your client supports it).

2. Zero-config path (DCR enabled)

Use this when your administrator has enabled Dynamic Client Registration. The assistant registers itself; you never touch /settings/applications.

Claude.ai custom connector

In Claude.ai, open Settings → Connectors and choose Add custom connector.
For the connector URL, paste the repository's MCP server URL:
```
https://<host>/api/v1/mcp/<owner>/<repo>
```
Save. Claude.ai contacts the server, discovers the OAuth endpoints, and registers itself automatically (this is the DCR step).
Claude.ai opens a Vetrix sign-in / consent page. Sign in if prompted, then review the consent screen — it requests the mcp:read scope for the repository. Click Authorize.
You are redirected back to Claude.ai and the connector shows as connected.

Gemini CLI

Add the Vetrix MCP server to your Gemini CLI MCP configuration, pointing at the same URL:
```
https://<host>/api/v1/mcp/<owner>/<repo>
```
Start the assistant. On first use it discovers the OAuth endpoints, registers itself (DCR), and opens your browser to the Vetrix consent screen.
Approve the mcp:read consent. The CLI captures the redirect on its loopback address and stores the token.

Make the first tool call

Once connected, ask the assistant a read-only question about the repository, for example "List the open issues in this repo" or "Show me the README". The assistant calls a Vetrix MCP tool, Vetrix checks the mcp:read token and your repository permissions, and returns the data. A successful answer confirms the connection end-to-end.

If the assistant reports that "Automatic client registration isn't supported by the MCP server," DCR is disabled on your instance — go to the manual path or ask an administrator to enable DCR (see Troubleshooting).

3. Manual path (DCR disabled)

Use this when automatic registration is not supported. You register an OAuth app yourself and hand its Client ID to the connector.

Claude.ai cannot use this path. The Claude.ai connector requires DCR; a manually pasted client_id fails for it with PKCE S256 code_challenge required. Clients that use a loopback redirect — such as gemini-cli — work fine here. See Troubleshooting for why.

3.1 Register an OAuth app

Sign in to Vetrix and open /settings/applications (the user OAuth applications console).
Click Register new application and fill in:
- Name — anything recognisable, e.g. Gemini CLI (my-repo). It is shown on the consent screen.
- Redirect URI — the assistant's OAuth callback. For example:
  - Claude.ai uses https://claude.ai/api/mcp/auth_callback (note that Claude.ai itself still requires DCR — see the warning above).
  - gemini-cli uses a loopback address such as http://127.0.0.1:<port>/oauth/callback. Use the exact callback your client prints; Vetrix accepts loopback redirects with any port.
- Scope — select mcp:read.
- Client type — public (assistants are public clients and use PKCE).
Save. Vetrix shows you a Client ID. Copy it. (A public client has no secret to store.)

For the full app-registration reference — scopes, redirect-URI rules, client types — see the OAuth2 developer guide.

3.2 Paste the Client ID into the connector

In your assistant's MCP / connector settings, open the Advanced settings for the Vetrix server.
Set the server URL to https://<host>/api/v1/mcp/<owner>/<repo>.
Paste the Client ID from step 3.1 into the Client ID field.
Save and connect. The assistant runs the OAuth authorization-code + PKCE flow against Vetrix, opens the consent screen, and you approve the mcp:read scope.

Make the first tool call

As in the zero-config path, ask the assistant a read-only question about the repository ("List the open issues", "Show me the README"). A successful answer confirms the connection.

Both paths converge on the same Vetrix consent screen. It shows:

The application name requesting access (the connector, or the app you registered in the manual path).
The scope requested — this should be mcp:read only.
The repository the access applies to.

Approve only if the application name and scope match what you expect. Approving grants the assistant a read-only token; you can revoke it at any time (see below).

5. Managing and revoking access

See and revoke the apps you have authorised — and the OAuth apps you registered in the manual path — at /settings/applications.
Revoking an authorisation immediately stops the assistant from reading the repository; reconnecting requires approving the consent screen again.
The token is read-only (mcp:read) and scoped to repositories you can already see, so revocation never affects your own access.

6. Troubleshooting

"Automatic client registration isn't supported by the MCP server"

This means Dynamic Client Registration is disabled on your Vetrix instance, so the assistant cannot register itself. You have two options:

Ask an instance administrator to enable DCR. Admins can turn it on under Admin → Settings → OAuth2 / Dynamic Client Registration. Once enabled, retry the zero-config path.
Use the manual path if your client supports it. The Gemini CLI does; the Claude.ai connector does not — Claude.ai requires DCR, so for Claude.ai an administrator must enable DCR.

Claude.ai fails with `PKCE S256 code_challenge required`

You pasted a client_id into the Claude.ai connector's Advanced settings (the manual path). The Claude.ai connector does not support the manual path — it only works through DCR. Remove the manually entered Client ID and use the zero-config path; if DCR is disabled, ask an administrator to enable it.

The client_id you entered is not a Vetrix OAuth app.

Do not paste a Google-SSO or other generic OAuth client ID (for example a …apps.googleusercontent.com ID, or a client ID from a "Sign in with Google/GitHub" provider). Those identify Vetrix's upstream identity providers, not an app registered against the Vetrix OAuth server, so Vetrix cannot find them and consent fails.

The only Client ID that works in the manual path is one you created yourself at /settings/applications (see section 3.1).

The assistant connects but cannot read anything

Confirm that your Vetrix account can already see the repository. mcp:read is additive — it never grants access beyond what your account already has. If you cannot open the repository in the Vetrix web UI, the assistant cannot read it either. Ask for repository access first, then reconnect.

Where to find the server URL

Copy it from the repository's Settings → MCP page, or build it by hand: https://<host>/api/v1/mcp/<owner>/<repo>.