MCP Server Authentication

Nexla MCP servers support two ways to authenticate: OAuth sign-in with Google or Microsoft, and a Nexla service key. This page covers connecting directly to a server you build or edit in MCP Studio. If you use Nexla's pre-built servers through a cloud marketplace or AI client directory listing, connect through the Nexla MCP Gateway instead.

Both methods reach the same server and the same tools. The URL you connect to decides which method the client uses. Whichever method you choose, every tool call runs on behalf of the person who authenticated.

Prerequisites

A Nexla account.
An active MCP server that you built or edited in MCP Studio.
For the service-key method, a Nexla service key. See Service Key.
Node.js, to run npx mcp-remote, if your client can only launch local servers (for example, Claude Desktop configured through claude_desktop_config.json).

Server URLs

Each server has three URLs:

https://api-genai.nexla.io/mcp/oauth/google/{server_key}
https://api-genai.nexla.io/mcp/oauth/azure/{server_key}
https://api-genai.nexla.io/mcp/service_key/{server_key}

URL	Sign-in
`/mcp/oauth/google/`	Sign in with a Google account
`/mcp/oauth/azure/`	Sign in with a Microsoft (Azure AD) account
`/mcp/service_key/`	Nexla service key in the `Authorization` header

The server key at the end of each URL ({server_key}) identifies the server. It is not a credential -- listing and calling tools requires an OAuth sign-in or a service key. Share the URL only with people who should use the server.

Find Your Server URLs

For a server you built or edited in MCP Studio:

Go to https://express.dev, open MCP Studio, and open the session where you built or edited the server.
In the right-hand pane, select the Build tab.
Scroll to Integration config. It appears after the server is built and CURRENT SERVER shows Active.

The Integration config panel has two tabs:

Quick Connect -- shows the Google OAuth URL and the Azure OAuth URL, each with a Copy button.
MCP Config -- shows ready-to-paste mcp.json blocks that run the server through mcp-remote, including a service-key version.

All three URLs share the same server key. To switch methods, change only the path segment -- for example, replace /mcp/service_key/ with /mcp/oauth/google/.

Choose a Method

MCP authorization is the part of the MCP standard that lets a client sign in to a remote MCP server with OAuth.

Scenario	Use
Hosted AI apps (Claude, ChatGPT and other hosted clients)	An OAuth URL
Your own desktop or IDE client	An OAuth URL if the client supports MCP authorization, otherwise a service key
Shared agents where each person must act as themselves	An OAuth URL
Scripts, CI, servers and other headless use	A service key
Organizations that sign in with Microsoft	The Azure OAuth URL

On-Behalf-Of Access

Every tool call runs on behalf of the authenticated caller:

OAuth -- the person who signed in.
Service key -- the Nexla user who owns the key.

Tools use only the credentials that person can access in their own Nexla account. A caller can't use another Nexla user's credentials or data unless they hold that user's service key. Nexla verifies access on every call.

warning

Everyone who uses a service key acts as its owner and reaches the owner's credentials and data. Do not share a service key across people. For agents that several people use, give each person an OAuth URL so each call runs as that person.

If the caller has no credential for a system a tool needs, the tool prompts them to add one through a secure Nexla link. The caller enters the credential in Nexla -- it never passes through the agent or the chat -- and then retries the request.

Credentials live in Nexla's vault. Agents call tools and never see raw credentials, tokens or secrets. Nexla handles token refresh, credential rotation and expiry. Every tool call is logged with who, what and when -- see Audit & Receipts.

You only need the OAuth URL. Nothing needs to be registered in Nexla for clients that support MCP authorization, and you do not enter a client ID or secret.

Paste the Google or Azure OAuth URL into your MCP client. For client-specific steps, see Connect Your MCP Client.
Sign in with your Google or Microsoft account in the browser window the client opens.

Behind the scenes, the server answers the client's first request with 401 and a WWW-Authenticate header that points to its protected-resource metadata. The client reads the metadata, registers itself with Nexla's authorization server through dynamic client registration, and completes an authorization-code flow with PKCE. The authorization server supports the refresh_token grant, so clients that use refresh tokens can renew access without asking you to sign in again.

OAuth Reference

Replace {provider} with google or azure.

Item	URL
Issuer	`https://api-genai.nexla.io/mcp/oauth/{provider}`
Authorization endpoint	`https://api-genai.nexla.io/mcp/oauth/{provider}/authorize`
Token endpoint	`https://api-genai.nexla.io/mcp/oauth/{provider}/token`
Registration endpoint	`https://api-genai.nexla.io/mcp/oauth/{provider}/register`
Protected-resource metadata	`https://api-genai.nexla.io/.well-known/oauth-protected-resource/mcp/oauth/{provider}`
Authorization-server metadata	`https://api-genai.nexla.io/.well-known/oauth-authorization-server/mcp/oauth/{provider}`

Both providers use the same settings:

Scopes -- openid, email, profile.
Grant types -- authorization_code, refresh_token.
Token endpoint authentication -- client_secret_post, client_secret_basic.
PKCE -- code challenge method S256.
Bearer tokens -- accepted only in the Authorization header.

Service Key

A service key authenticates as the Nexla user who owns it. Every tool call made with the key runs as that user.

To create a key in the Nexla platform:

Go to Settings > Authentication.
Click Create Service Key.
Enter a name and description for the key.
Copy the key. Nexla shows it only once.

To get a service key in Express instead, open the profile menu at the bottom left and select Get Nexla API key. The API key it shows is a service key.

See Service Keys for details on creating and managing keys. For MCP servers, send the service key itself as the Bearer token -- you do not need to exchange it for a session token first.

Send the key in the Authorization header of every request to the /mcp/service_key/ URL:

Authorization: Bearer YOUR_NEXLA_SERVICE_KEY

warning

Treat a service key like a password. Keep it in an environment variable or a secret store, never commit it to source control, and revoke and replace it if it is exposed.

Connect Your MCP Client

The examples below use the server name nexla-account-research. Replace it with any name you like, and replace {server_key} with your server key. The OAuth examples use the Google URL. To sign in with Microsoft, use the /mcp/oauth/azure/ URL instead.

tip

In MCP Studio, the MCP Config tab of Integration config gives you a ready-made mcp.json snippet with your server URL filled in. Replace the key placeholder in the Authorization header with your service key.

Claude (Custom Connector)

In Claude, open Settings > Connectors and add a custom connector.
Paste the Google or Azure OAuth URL.
Connect and sign in.

Claude Desktop (Config File)

Claude Desktop's config file only launches local (stdio) servers, so these snippets run mcp-remote through npx to reach the remote URL. Install Node.js first. To use OAuth without the config file, add the server as a custom connector instead (see Claude (Custom Connector)).

Open claude_desktop_config.json, either from Claude Desktop's developer settings or directly at:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add one of the configurations below.
Restart Claude Desktop.

With a service key:

{
  "mcpServers": {
    "nexla-account-research": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "--header",
        "Authorization: Bearer YOUR_NEXLA_SERVICE_KEY",
        "https://api-genai.nexla.io/mcp/service_key/{server_key}"
      ]
    }
  }
}

note

On Windows, some clients do not pass the space inside the header argument correctly, so the key is not sent. If that happens, move the value into an environment variable:

{
  "mcpServers": {
    "nexla-account-research": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "https://api-genai.nexla.io/mcp/service_key/{server_key}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_NEXLA_SERVICE_KEY"
      }
    }
  }
}

With OAuth (mcp-remote opens a browser window for you to sign in):

{
  "mcpServers": {
    "nexla-account-research": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api-genai.nexla.io/mcp/oauth/google/{server_key}"
      ]
    }
  }
}

Claude Code

With OAuth, add the server, then run /mcp in Claude Code and authenticate:

claude mcp add --transport http nexla-account-research https://api-genai.nexla.io/mcp/oauth/google/{server_key}

With a service key:

claude mcp add --transport http nexla-account-research https://api-genai.nexla.io/mcp/service_key/{server_key} --header "Authorization: Bearer $NEXLA_SERVICE_KEY"

Cursor

Edit ~/.cursor/mcp.json, or .cursor/mcp.json in a project.

With OAuth:

{
  "mcpServers": {
    "nexla-account-research": {
      "url": "https://api-genai.nexla.io/mcp/oauth/google/{server_key}"
    }
  }
}

With a service key:

{
  "mcpServers": {
    "nexla-account-research": {
      "url": "https://api-genai.nexla.io/mcp/service_key/{server_key}",
      "headers": {
        "Authorization": "Bearer YOUR_NEXLA_SERVICE_KEY"
      }
    }
  }
}

VS Code

Edit .vscode/mcp.json in your workspace.

With OAuth:

{
  "servers": {
    "nexla-account-research": {
      "type": "http",
      "url": "https://api-genai.nexla.io/mcp/oauth/google/{server_key}"
    }
  }
}

With a service key, VS Code prompts for the key and stores it instead of keeping it in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "nexla-service-key",
      "description": "Nexla service key",
      "password": true
    }
  ],
  "servers": {
    "nexla-account-research": {
      "type": "http",
      "url": "https://api-genai.nexla.io/mcp/service_key/{server_key}",
      "headers": {
        "Authorization": "Bearer ${input:nexla-service-key}"
      }
    }
  }
}

ChatGPT

In ChatGPT, go to Settings > Apps & Connectors > Advanced settings and turn on Developer mode.
In Apps, click Create app.
In Server URL, paste your Google or Azure OAuth URL, set Authentication to OAuth, and continue.
Sign in, then confirm the app shows as Connected.

For screenshots of these ChatGPT screens, see Integrate with ChatGPT. Enter your own OAuth URL, not the Server URL shown in that guide.

Other Clients

For Gemini, Microsoft Copilot, Lovable and other MCP clients:

If the client supports remote MCP servers with OAuth, use an OAuth URL.
Otherwise, use the /mcp/service_key/ URL and send the service key in the Authorization header.
If the client supports only local (stdio) servers, use npx mcp-remote as shown for Claude Desktop.

Verify the Connection

After you connect, your client lists the server's own scoped tools.

To check a service key from the command line, list the server's tools:

curl -s https://api-genai.nexla.io/mcp/service_key/{server_key} \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A working key returns a JSON-RPC result with a tools array. The response can arrive as an SSE data: line; the JSON after data: is the result. If the response contains an error instead, see Connected but No Tools.

Troubleshooting

401 Invalid Token After Signing In

A 401 on the first request is expected -- it starts sign-in. The problem is when the client keeps getting 401 with error="invalid_token" after you sign in. The description reads:

Authentication failed. The provided bearer token is invalid, expired, or no longer recognized by the server. To resolve: clear authentication tokens in your MCP client and reconnect. Your client should automatically re-register and obtain new tokens.

Clear the connector's stored tokens, or remove the connector, then reconnect and sign in again.

Connected but No Tools

On a /mcp/service_key/ URL, the client connects but lists no tools, or returns Request context not available — authentication or export lookup failed. Check that:

The header is exactly Authorization: Bearer YOUR_NEXLA_SERVICE_KEY, with your key in place of the placeholder.
The service key is active and has not been revoked.
The server key at the end of the URL is copied in full.
The server is active. In MCP Studio, the Build tab shows Active under CURRENT SERVER.
On Windows, the header is actually sent. See the note under Claude Desktop (Config File).

Asked to Connect an Account

The tool needs a credential that is not in your Nexla account. Open the secure Nexla link, add the credential in Nexla, then retry the request. See On-Behalf-Of Access.

Connected System Rejects the Credential

A tool fails with an authentication error from the connected system. The credential in your Nexla account for that system no longer works. In the Nexla platform, go to Integrate > Credentials, open the credential, update its login details, then retry the request.

Headless jobs cannot complete a browser sign-in. Use the /mcp/service_key/ URL with a service key.

Signed In with the Wrong Account or Provider

Remove the connector from your client and reconnect it. Use the Azure OAuth URL to sign in with a Microsoft account and the Google OAuth URL to sign in with a Google account.

Next Steps

MCP Studio -- Build a task-specific MCP server and copy its connection details from the Build tab.
Pre-built MCP Servers -- Ready-made servers you access through the Nexla MCP Gateway.
Nexla MCP Gateway -- The single endpoint for the pre-built MCP servers you get through cloud marketplace and AI client directory listings.
Audit & Receipts -- Review the record of every tool call made on your behalf.
MCP Protocol API -- Technical reference for the MCP protocol endpoints.

Prerequisites​

Server URLs​

Find Your Server URLs​

Choose a Method​

On-Behalf-Of Access​

OAuth Sign-In​

OAuth Reference​

Service Key​

Connect Your MCP Client​

Claude (Custom Connector)​

Claude Desktop (Config File)​

Claude Code​

Cursor​

VS Code​

ChatGPT​

Other Clients​

Verify the Connection​

Troubleshooting​

401 Invalid Token After Signing In​

Connected but No Tools​

Asked to Connect an Account​

Connected System Rejects the Credential​

A Script or CI Job Cannot Sign In​

Signed In with the Wrong Account or Provider​

Next Steps​

Prerequisites

Server URLs

Find Your Server URLs

Choose a Method

On-Behalf-Of Access

OAuth Sign-In

OAuth Reference

Service Key

Connect Your MCP Client

Claude (Custom Connector)

Claude Desktop (Config File)

Claude Code

Cursor

VS Code

ChatGPT

Other Clients

Verify the Connection

Troubleshooting

401 Invalid Token After Signing In

Connected but No Tools

Asked to Connect an Account

Connected System Rejects the Credential

A Script or CI Job Cannot Sign In

Signed In with the Wrong Account or Provider

Next Steps