Skip to content

Guides

OAuth or API key: how MCP clients sign in

How MCP clients authenticate to remote MCP servers: bearer API keys, the OAuth 2.1 flow, which clients use which, security trade-offs and fixes for 401s.

A remote MCP server has to know who is calling it. It needs that to decide what the caller may do, to count usage against the right account and to stop strangers from using it at all. MCP clients prove who they are in one of two ways: they send an API key you created and pasted into their configuration, or they run an OAuth sign-in in your browser and keep the token it returns.

Both end in the same place. Every request the client sends carries a bearer token in the Authorization header, and the server checks it. What differs is where that token comes from, how long it lives and who has to handle it.

This guide explains both methods, how the OAuth flow in the MCP specification works, which clients use which, the security trade-offs, what changes for teams and how to fix the errors you are most likely to see. If MCP itself is new to you, start with what is an MCP server.

Why remote MCP servers need authentication

MCP servers come in two shapes. A local server runs on your machine as a process the client starts, and the two talk over standard input and output. A remote server runs somewhere on the internet, and the client talks to it over HTTP.

The MCP specification treats them differently. Authorization is optional in MCP, and when it is used:

  • Servers on an HTTP transport should follow the specification's authorization rules, which are built on OAuth.
  • Servers on the standard input and output transport should not; they take their credentials from the environment instead, for example from environment variables the client sets when it starts them.

So the question of OAuth or API key is a question about remote servers. A local server you start yourself already runs with your permissions on your machine. A remote server is reachable by anyone who knows its address, so it must check every request.

API keys and bearer tokens

What an API key is

An API key is a long random string that a service creates for your account. Whoever presents it is treated as you. You create it once in the service's dashboard, copy it into your client's configuration, and the client sends it with every request.

API keys are simple, which is their main strength and their main weakness. There is no sign-in flow, no browser and no expiry to manage. There is also nothing that stops a copied key from working anywhere until you revoke it. Our guide to API key management covers keys in general; this section is about how they are used with MCP.

How a bearer token is sent

MCP clients send credentials in the HTTP Authorization header with the Bearer scheme, the format defined for OAuth bearer tokens. A bearer token is any token where possession is enough: the server does not ask for anything else, so whoever bears it can use it. An API key sent this way is a bearer token too.

The header looks like this:

Text
Authorization: Bearer YOUR_API_KEY

Three details matter:

  • The word Bearer, then one space, then the key. No quotes, no colon after Bearer, no extra spaces.
  • The header goes on every request, not only the first one.
  • The connection must use HTTPS. A bearer token sent over plain HTTP can be read by anyone on the path.

The MCP specification also says access tokens must not be put in the URL query string. URLs end up in logs, browser history and proxy records, so a token there leaks easily. Some services still accept keys in the URL for convenience; avoid that form when a header is available.

Where clients keep the key

Editors and command line clients usually read MCP servers from a JSON or TOML file, or add them with one command. A typical JSON entry for a remote server with a key looks like this:

JSON
{
  "mcpServers": {
    "multitaskai": {
      "url": "https://mcp.multitaskai.com",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The exact shape varies. Some clients want a type field, some call the URL field httpUrl, some wrap servers in a servers object instead of mcpServers, and TOML-based clients use their own keys. Command line clients often take the header as a flag:

Shell
claude mcp add --transport http multitaskai https://mcp.multitaskai.com --header "Authorization: Bearer YOUR_API_KEY"

Several clients can also read the key from an environment variable so it never sits in the file. The setup guides show the exact format for each client.

OAuth 2.1 in MCP

The idea

OAuth is a way to give an application access to an account without giving it your password. Instead of pasting a secret, you sign in on the service's own page in your browser and approve the application. The service then hands the application a token that represents that approval.

The MCP specification builds its authorization on the OAuth 2.1 draft and a handful of related standards. In OAuth terms, the MCP server is a resource server, the MCP client is an OAuth client, and a separate authorization server signs you in and issues tokens. The authorization server can be part of the same service as the MCP server or a different system, such as a company's identity provider.

What happens when you connect

From the user's side, connecting looks like this: you paste the server URL into the client, a browser window opens, you sign in and approve, and the window closes. Behind that, the specification describes these steps:

  1. The first request fails on purpose. The client calls the MCP server without a token. The server answers 401 Unauthorized with a WWW-Authenticate header that points to its protected resource metadata, and it may name the scopes it wants.
  2. The client discovers the authorization server. It fetches the protected resource metadata, a small JSON document the MCP server must publish, which says which authorization server issues tokens for it. Then it fetches that authorization server's own metadata to learn its endpoints.
  3. The client identifies itself. It needs a client ID. The specification offers three ways: a Client ID Metadata Document, where the client ID is an HTTPS URL pointing to a JSON document that describes the client; a client ID registered in advance; or Dynamic Client Registration, where the client registers itself through an API. The current specification recommends metadata documents and keeps Dynamic Client Registration only for backwards compatibility with authorization servers that do not support them.
  4. You sign in and consent. The client opens your browser at the authorization server with a PKCE challenge and a resource parameter naming the MCP server. You sign in, see what the client is asking for and approve it.
  5. The client gets a code and swaps it for tokens. The browser is redirected back to the client with a short-lived authorization code. The client checks that the response came from the authorization server it expected, then exchanges the code, its PKCE verifier and the resource parameter for an access token and, if the server issues one, a refresh token.
  6. Every request carries the access token. From now on the client sends Authorization: Bearer with the access token on every request, exactly like an API key.

PKCE in plain terms

PKCE, short for Proof Key for Code Exchange, protects the step where the authorization code travels through your browser. Before it opens the browser, the client invents a random secret and sends only a fingerprint of it. When it exchanges the code for tokens, it reveals the secret itself. An attacker who intercepted the code would not have the secret, so the code is useless to them. OAuth 2.1 builds this in for the authorization code flow, and MCP's flow uses it.

Access tokens, refresh tokens and expiry

Access tokens are usually short-lived. When one expires, the client uses its refresh token to get a new one in the background, without sending you back to the browser. If refresh tokens are not issued, or the refresh token itself expires or is revoked, the client has to run the sign-in again. The specification lets the authorization server decide whether to issue refresh tokens, so clients must not assume they will get one.

Audience binding

The resource parameter in the flow is there for a reason. It tells the authorization server which MCP server the token is for, and the specification requires MCP servers to accept only tokens issued for them. A token for one server should not work on another. The specification also forbids token passthrough: an MCP server must not accept a token meant for something else and forward it to another service.

Scopes and step-up

Scopes describe what a token allows. A server can ask for minimal scopes at first and, when a request needs more, answer 403 Forbidden with insufficient_scope and the scopes it needs. The client can then run the sign-in again for the larger set. Many MCP servers, including simple ones, use a single scope for everything; the mechanism is there for servers where read and write access need to be separate.

Which clients use which

In practice the split follows the type of client.

Connectors in Claude and ChatGPT use OAuth. You add a custom connector with the server's URL, the app runs the sign-in in your browser and keeps the tokens on its side. You never see or paste a secret. In Claude, a connector you add on the web also appears in the desktop and mobile apps for the same account. See Claude and ChatGPT for the steps.

Editors and command line clients usually use an API key. Claude Code, Cursor, VS Code, Windsurf, Gemini CLI and Codex CLI read MCP servers from a configuration file or a command, and an API key in a header is one line there. Several of these clients can also run an OAuth flow for servers that offer one, but a key is the simplest setup when you work across machines, scripts and terminals. See Claude Code, Cursor, VS Code, Gemini CLI and Codex CLI.

Client Typical method Where the credential lives
Claude (web, desktop, mobile) OAuth connector Held by Claude after you approve
ChatGPT OAuth connector Held by ChatGPT after you approve
Claude Code API key Command flag or configuration file
Cursor API key mcp.json
VS Code API key MCP configuration file, optionally from an environment variable
Windsurf API key mcp_config.json
Gemini CLI API key settings.json or command flag
Codex CLI API key config.toml, optionally from an environment variable
Other MCP clients over HTTP Whichever the client supports Client configuration

OAuth and API keys compared

API key OAuth
Setup Create a key, paste it into config Paste the URL, sign in in the browser
Secret handled by you Yes, you copy and store it No, the client stores the tokens
Lifetime Until you revoke it Short access tokens, refreshed in the background
Tied to a person To the account that created it To the person who signed in
Works without a browser Yes Needs a browser for the first sign-in
Works in scripts and CI Yes Awkward, needs an interactive sign-in
Scope Usually the whole account, unless the service offers scoped keys Can be limited by scopes
Revocation Delete the key in the dashboard Revoke the connection or sign out
Main risk A copied key works anywhere until revoked A stolen token works until it expires or is revoked

Neither is strictly better. OAuth is safer by default because there is no long-lived secret for you to mishandle. API keys are simpler to automate and work in places where a browser sign-in is impractical.

Security trade-offs

Keys in configuration files

An API key in a configuration file is only as safe as that file. Anything that can read it can use the key, including sync tools, screen shares and AI agents with file access on the same machine. Keep MCP configuration in your user folder and check file permissions on shared machines.

Never commit keys

Project-level configuration files are convenient because they travel with the repository. That is exactly why they must not contain keys. If a project configuration needs a server, either reference an environment variable for the key or keep the file out of version control. If a key is ever committed, treat it as leaked: revoke it and create a new one. Removing it in a later commit does not remove it from the history.

Environment variables

Several clients can read the header value or the key from an environment variable, so the configuration file only names the variable. That keeps the key out of files you might share, and you can load it from your shell profile, a password manager's command line tool or a secrets manager. Remember that environment variables are visible to the processes you start, so they reduce the risk of accidental sharing rather than remove every risk.

Rotation

Rotate keys on a schedule and immediately when a device is lost, a laptop is handed over or a key may have been exposed. Rotation is painless if you keep track of where each key is used. The simplest way is one key per device or per tool, named so you can tell them apart.

Scoping

Give each key as little power as the service allows. If a service offers read-only keys, per-project keys or keys limited to certain tools, use them. With OAuth, approve only the scopes the client needs; a well-behaved client asks for the minimum.

Revocation

Know how to revoke before you need to. For API keys, that means deleting the key in your account, which stops it at once. For OAuth connections, it means disconnecting the connector in the client and, where the service offers it, revoking the authorization on the service's side. Access tokens that are already issued may keep working until they expire, which is one reason they are kept short.

Teams and enterprises

For a single person, the choice is mostly about convenience. In a team, it is about accountability.

  • One person, one credential. Each person should connect with their own account, through OAuth or their own key. A shared key makes it impossible to tell who did what and forces everyone to rotate when one person leaves.
  • Offboarding. OAuth connections tied to a company identity provider stop working when the account is disabled. Personal API keys must be revoked one by one, so keep a list.
  • Admin-managed connectors. On team and enterprise plans of Claude and ChatGPT, an owner or admin may need to add or approve a custom connector for the organisation before members can connect. Each member then signs in with their own account.
  • Automation. Scripts, scheduled jobs and CI pipelines cannot click through a browser sign-in. Give them a dedicated key that belongs to a service account or a bot account, stored in the pipeline's secret store, and nothing else.
  • Usage and quotas. Usage counts against the account the credential belongs to. If several people share an account, they share its limits.
  • Policy. Decide which MCP servers are approved, who may add new ones and where configuration files may live. MCP servers can read and act on data, so they deserve the same review as any other integration.

Troubleshooting

401 Unauthorized with an API key

The server did not accept the credential. Check, in order:

  • The header name is Authorization, and the value starts with Bearer and a single space.
  • The key was copied completely, without a leading or trailing space, a line break or surrounding quotes inside the value.
  • The key has not been revoked or replaced.
  • The header sits in the field your client reads. Field names differ between clients, and a header in the wrong place is silently ignored.
  • An environment variable reference really expands. If the client does not support variables in that field, it sends the literal text instead of your key.

Restart the client or reload its MCP servers after changing the configuration. Many clients read the file only at start-up.

401 after it worked before

With an API key, the key was most likely revoked or rotated. With OAuth, the access token expired and the refresh failed, or the connection was revoked. Disconnect and reconnect the connector, or run the client's sign-in again.

The browser sign-in never completes

Pop-up blockers, strict privacy extensions and corporate proxies can interrupt the redirect back to the client. Allow pop-ups for the client, try a different browser, and make sure you are signed in to the right account on the service. In desktop clients, the redirect may go to a local address; firewalls that block local connections can break it.

403 Forbidden

The credential is valid but not allowed to do this. With OAuth, the token may lack a scope and the client needs to sign in again with more. With a key, the key may be restricted, or the account may not have access to that feature.

Connection errors before authentication

If the client cannot even reach the server, the problem is the address or the transport, not the credential. Check the URL and its path, and make sure the client is set to Streamable HTTP rather than the older SSE transport when the server expects it.

Requests refused after a while

Services limit usage per account. When the limit is used up, requests are refused until it resets. That is a quota, not an authentication failure, and it shows up the same way whichever method you used.

How MultitaskAI handles sign-in

MultitaskAI is a remote MCP server at one endpoint that gives AI agents 166 exact tools: DNS, WHOIS and SSL lookups, JSON repair, regex testing, conversions, image resizing and more. It works with Claude, ChatGPT, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Codex CLI and any MCP client over HTTP.

It supports both methods described in this guide:

  • Connectors in Claude and ChatGPT sign in with OAuth. You add the endpoint as a custom connector, approve it once in your browser, and the app keeps the token.
  • Editors and command line clients send a MultitaskAI API key as a bearer token in the Authorization header. You create the key in your account and paste it into the client's configuration in place of YOUR_API_KEY.

Both count against the same account. Every signed-in account gets 100 free requests a day, reset at midnight UTC, and MultitaskAI Pro removes the limit for €9 a month; see pricing. The setup overview has the endpoint and links to a guide for each client, and tools lists everything the server can do.

Frequently asked questions

Is OAuth more secure than an API key?

Usually, yes, because you never handle a long-lived secret and access tokens expire. An API key is safe enough when you store it carefully, keep it out of shared files and revoke it when needed.

Can I use an API key in Claude or ChatGPT connectors?

Connectors in Claude and ChatGPT are built around OAuth: you paste the server URL and sign in in your browser. Use an API key in editors and command line clients instead.

Why does my editor use an API key when it supports OAuth?

A key is one line of configuration that works the same on every machine, in every terminal and in scripts, with no browser step. If your client and the server both support OAuth, you can use it there too.

Do API keys expire?

That depends on the service. Many keys last until you revoke them, which is why rotation matters. OAuth access tokens are short-lived by design and refreshed in the background.

What happens if my API key leaks?

Revoke it in your account at once and create a new one. Then update every client that used it. If it was committed to a repository, assume it was copied, even if you removed it later.

Does the MCP specification require OAuth?

No. Authorization is optional in MCP. When an HTTP-based server uses it, the specification says it should follow its OAuth-based rules. Servers that run locally over standard input and output take credentials from the environment instead.

What is the difference between a 401 and a 403?

A 401 means the server did not accept who you are: the credential is missing, malformed, expired or revoked. A 403 means it knows who you are but will not allow this request, for example because a scope or permission is missing.

Do OAuth and API key requests count the same?

On MultitaskAI, yes. Both count against the daily requests of the account that signed in or created the key.

Give your agent 433 tools in a minute

Connect MultitaskAI to your MCP client and ask in plain words. 100 requests a day are free.