What MCP Remote Does
MCP Remote is a small command-line bridge for an MCP client that can launch local stdio programs but cannot connect to a remote MCP endpoint itself. Instead of asking the client to speak HTTP and complete an OAuth flow, the client starts mcp-remote locally. The bridge connects to the remote URL and passes MCP messages between the two transports.
That distinction matters. MCP Remote is not the remote server, and it does not turn an arbitrary local server into an internet service. It is a compatibility layer for a remote server that already exists, especially one that needs browser-based authorization. If your client already supports the server's remote transport and authorization flow directly, use the native connection first. There is less moving machinery to debug.
The specific package covered here is the grade-A MCP Remote listing on MCPVault. Its repository documents the bridge configuration for clients that use the common command and args shape. The vault snapshot used for this guide was taken on 2026-08-30 UTC: the listing was grade A, MIT licensed, TypeScript, and showed 1,568 GitHub stars. It was not marked verified, so the grade is a maintenance and project-quality signal, not proof that a live handshake was performed.
When You Need a Local Bridge
Remote MCP endpoints normally expose an HTTPS URL. A desktop client that only knows how to start a command cannot put that URL directly into its local-server configuration. MCP Remote fills that gap: the client talks over standard input and output to a process on your computer, and that process handles the network-facing connection.
This is useful when a provider supplies an MCP URL plus an OAuth sign-in, but the client only accepts a command. It can also be useful while a client has partial support for remote MCP. The bridge gives the client a local process to launch while keeping the service endpoint remote.
Do not use it as a way to bypass a provider's authentication requirements. A remote service still controls its own authorization. MCP Remote can open the login flow and manage the resulting session, but it cannot grant access to an account you do not control.
A Tested Command Shape
On 2026-08-30, we ran the following command against the current package:
npx -y mcp-remote@latest --help
It returned:
Usage: mcp-remote <https://server-url> [callback-port] [--debug]
That is a small but important implementation check. The remote URL is positional. Do not paste --url into a copied configuration unless the version you install documents that flag. The client configuration below passes the endpoint as the second package argument, exactly as the tested usage line requires.
Replace the example endpoint with the HTTPS URL supplied by your MCP provider:
{
"mcpServers": {
"remote-example": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"https://remote.example.com/mcp"
]
}
}
}
The package documentation also shows older SSE-style endpoints. Use the endpoint format the remote service actually publishes. A trailing /sse endpoint and a /mcp endpoint are not interchangeable guesses. If the provider has setup instructions, copy its URL exactly.
For Claude Desktop, this object belongs in the mcpServers object in its desktop configuration file. Other local clients often use the same command-and-arguments model but store their configuration elsewhere. The value to preserve is the bridge pattern: the client launches npx, npx launches mcp-remote, and mcp-remote connects to the remote URL.
OAuth, Callback Ports, and First Connection
Many remote MCP servers use OAuth. On the first connection, MCP Remote may open a browser window so you can sign in and approve access. After the provider redirects the browser back to the local callback, the bridge can complete the token exchange and continue the MCP session.
The optional callback port is the second positional value after the URL. Only set one when the server or identity provider has a registered redirect URI that requires it. For example:
{
"mcpServers": {
"remote-example": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"https://remote.example.com/mcp",
"9696"
]
}
}
}
An explicit port is not a harmless preference. OAuth providers compare the callback URL with what they expect. If your provider documents a specific callback, use that exact value. If it does not, leave the port out and let the bridge use its documented default behavior.
If sign-in fails, add --debug after the URL and any callback port, restart the client, then inspect the resulting logs before changing several settings at once. A useful debugging sequence is: confirm the endpoint URL, confirm the account can sign in in a normal browser, then retry with debug logging. That keeps a transport error from being mistaken for an OAuth error.
Put Credentials in a Header File
Some remote endpoints use a static API key or another header instead of an interactive OAuth session. MCP Remote supports custom headers. The tempting configuration puts a bearer token directly in args, but that can expose it in the local process list. It also makes it easy to accidentally commit the token when you version-control client configuration.
Use a header file instead when the package and your client support it. Create a file that only your user account can read, for example ~/.config/mcp/remote-headers.txt:
Authorization: Bearer replace-with-your-token
Then reference the file:
{
"mcpServers": {
"remote-example": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"https://remote.example.com/mcp",
"--header-file",
"/absolute/path/to/remote-headers.txt"
]
}
}
}
The upstream README says an unreadable header file is an error, rather than silently continuing unauthenticated. That makes a mistyped path visible early. It is also why this guide prefers the file approach: it separates a secret from the client configuration and avoids placing it in command arguments.
Before connecting a server to data you care about, review the server's scopes and tool list. A bridge does not reduce the privileges that the remote server receives. Use MCPVault quality grades to compare maintenance signals, then inspect the project's own authorization and privacy documentation before approving access.
Check the Server, Not Just the Bridge
MCP Remote has a narrow job. It can make a remote endpoint usable from a local-only client, but it cannot tell you whether that endpoint is safe, available, or appropriate for your account. Evaluate both parts separately.
First, verify that the endpoint came from the service owner, not a copied forum comment. Second, check whether the requested scopes match the tools you intend to use. Third, start with a low-risk account or a read-only integration when the provider permits it. Finally, remove the configuration entry and revoke access at the provider if you no longer need the connection.
For a wider starting point, browse MCP servers in the vault and filter for the capability you need. The listing is a discovery record, while the remote service's own documentation remains the source of truth for its URL and authorization requirements.
Common Problems
The client says the server will not start
Run the tested command in a terminal first. If npx -y mcp-remote@latest --help cannot return its usage line, resolve Node.js or package-install issues before editing client JSON. A terminal test narrows the problem to either the local runtime or the client configuration.
The browser sign-in completes but the client remains disconnected
Confirm that the callback port matches the provider's expected redirect URI when you set one explicitly. Then retry with --debug and check that the remote URL is the provider's current endpoint. Do not repeatedly clear authentication state without first capturing the error, because the first useful clue is often in the failed exchange.
My endpoint requires a token
Prefer --header-file with a user-readable-only file over putting a bearer token in args. Keep the file outside a repository and rotate the token through the provider if it is ever pasted into a ticket, terminal history, or committed configuration.
Frequently Asked Questions
Does MCP Remote host an MCP server for me?
No. MCP Remote is a local bridge that connects a command-based client to an already hosted remote MCP server. You still need a real endpoint supplied by the service owner or one you deploy yourself.
Does MCP Remote work with Claude Desktop?
The upstream configuration documents the standard command-and-arguments pattern used by Claude Desktop. Add the bridge as a local command server, then use the remote endpoint URL supplied by your provider.
Should I use an SSE URL or an MCP URL?
Use the exact URL the remote server documents. The package supports remote connection workflows, but it cannot infer which path your provider exposes. Do not change /mcp into /sse, or the reverse, unless the provider explicitly documents both.
How do I evaluate an MCP Remote listing?
Start with the MCP Remote listing, its grade explanation, repository activity, license, and documentation. A quality grade is useful context, but verify a remote server's endpoint, scopes, and authorization behavior separately.
Your server in the vault.
If you built an MCP server, claim the listing so developers can find its current setup details and project link. Verification is free during early access and helps users distinguish a live tested endpoint from an auto-indexed record.
Claim your listing or submit a server if it is not indexed yet.
Evidence Receipt
- Snapshot date: 2026-08-30 UTC. MCPVault record:
punkpeye-mcp-remote, grade A, MIT, TypeScript, 1,568 stars, unverified. - Official implementation source: https://github.com/punkpeye/mcp-remote/blob/main/README.md
- Package source: https://www.npmjs.com/package/mcp-remote
- Command tested:
npx -y mcp-remote@latest --help, returnedUsage: mcp-remote <https://server-url> [callback-port] [--debug]. - Listing and internal destination checks:
/servers/punkpeye-mcp-remote,/docs/grades,/servers, and/claimeach returned HTTP 200 during drafting.