An MCP Gateway connection is reached over HTTP. Your client needs two things: an endpoint URL and an Authorization header. Where the endpoint lives depends on one connection setting, so start there.

Two tokens, two different jobs

Almost every MCP setup problem is these two being confused. They are unrelated.

	Proxy token	Upstream credential
Proves	You are allowed to use this hoop connection	Hoop is allowed to use the MCP server
Set by	Each user, in their MCP client config	An admin, once, on the connection
Looks like	`mcpproxy-a1b2c3…`	A Stripe key, a GitHub PAT, an OAuth token
Travels	Your client → hoop	Hoop → the MCP server
Seen by the model	Never	Never

This page is about the proxy token. For the upstream credential, see MCP Server Catalog.

Neither token reaches the model or its context window. Your client sends the proxy token to hoop; hoop authenticates you, applies tool policy and masking, then talks to the MCP server with the connection’s own credential.

Which endpoint do I use?

Gateway endpoint

For streamable-http, sse and stdio connections. A shared URL on your hoop gateway. Nothing to install.

Local endpoint

For client-stdio connections. hoop connect opens a port on your own machine and runs the MCP server there.

Ask your admin which transport the connection uses, or open the connection in the web app and read the Transport field.

Path A — Gateway endpoint

Use this for remote servers (streamable-http, sse) and for agent-run stdio servers. Nothing is installed on your machine.

Open the connection

In the web app, go to Resources, pick the MCP Gateway connection, and click Connect.

Copy the endpoint and token

The modal shows an MCP endpoint ending in /mcp and an Authorization header value beginning mcpproxy-. It also renders a ready-to-paste config block for Claude Code, Cursor and Devin.

Add it to your client

Paste the block for your client, or use the commands below.Claude Code

claude mcp add --transport http hoop \
  https://hoop.acme.com/mcp \
  --header "Authorization: mcpproxy-YOUR-TOKEN"

Or in .mcp.json:

{
  "mcpServers": {
    "hoop": {
      "type": "http",
      "url": "https://hoop.acme.com/mcp",
      "headers": {
        "Authorization": "mcpproxy-YOUR-TOKEN"
      }
    }
  }
}

Cursor — ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

{
  "mcpServers": {
    "hoop": {
      "url": "https://hoop.acme.com/mcp",
      "headers": {
        "Authorization": "mcpproxy-YOUR-TOKEN"
      }
    }
  }
}

Devin — .devin/mcp_config.json:

{
  "mcpServers": {
    "hoop": {
      "transport": "http",
      "url": "https://hoop.acme.com/mcp",
      "headers": {
        "Authorization": "mcpproxy-YOUR-TOKEN"
      }
    }
  }
}

Restart the client and verify

Restart your MCP client, then ask it to list its tools. Denied tools are absent by design: hoop removes them from the catalog before the model sees them, so the model never attempts a call you would have blocked.

Claude Code treats an entry that has a url but no "type" as a stdio server and silently skips it. Cursor infers the transport from url and needs no discriminator. Devin uses "transport". Copy the block for your client rather than adapting another one.

Path B — Local endpoint (`client-stdio`)

Use this when the connection’s transport is client-stdio. The MCP server runs on your machine, so it sees your working tree, your SSH agent and your logged-in CLIs. Every tool call is still inspected by hoop first. Here is what actually happens:

Your MCP client
 └─> hoop connect      a local port on your machine
      └─> hoop gateway
           └─> agent   policy, guardrails, masking, audit
                └─> back to hoop connect
                     └─> the MCP server, on your machine

The request leaves your machine, gets inspected, and comes back. That round trip is the point: the server runs locally, but nothing skips policy.

Install the hoop CLI

brew install hoophq/brew/hoop

Other platforms are covered in the CLI documentation.

Install the MCP server's runtime

The command the admin configured runs on your machine, so its runtime must be there. An npx-based server needs Node; a uvx-based one needs Python and uv. Ask your admin what the command is, or read it from the connection page.

hoop login
hoop connect my-mcp-connection

The CLI prints the endpoint to use:

---------------------mcp-connection-------------------
     endpoint=http://127.0.0.1:8081/mcp
------------------------------------------------------
ready to accept connections!

Leave this running. Closing it ends the session and stops the MCP server process. Pass --port 9000 if 8081 is taken.

Point your client at the local endpoint

Same config as Path A with one difference: the URL is the local one the CLI printed. No Authorization header is needed — hoop connect already authenticated you.

{
  "mcpServers": {
    "hoop": {
      "type": "http",
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

Use it

Restart your MCP client. The first tool call starts the MCP server on your machine; hoop stops it when you end the session. Nothing runs until you actually use the connection.

Use the endpoint the CLI printed, not the one in the web app’s Connect modal. A client-stdio connection is only reachable through your own hoop connect session — that is the whole point of the transport.

Each user gets their own MCP server process. Two people on the same connection never share state, and neither sees the other’s files.

Configuring the upstream credential

Everything above is how you reach hoop. This is how hoop reaches the MCP server, and it is an admin task done once per connection.

Static token

The provider issues a long-lived key — a Stripe secret key, a GitHub PAT, a Datadog API key — and hoop sends it on every request.

Create the connection

Resources → New → MCP Gateway. Name the role.

Pick the server

Choose it from the MCP Server dropdown. Hoop fills in the endpoint and transport, then shows one token field labelled with the header that provider expects.

Paste the key

Paste the credential. Select Secrets Manager as the source to have hoop fetch it from AWS Secrets Manager or HashiCorp Vault at connection time instead of storing it.

Set a tool policy

Deny destructive tools or hold them for review before you hand the connection out. Tool-level control is the reason to route MCP through a gateway.

The header name must be exactly what the provider documents. Context7 wants CONTEXT7_API_KEY; Google Maps wants X-Goog-Api-Key. A token under the wrong name is an unauthenticated request, and the error the server returns will not tell you that. Hoop uses the documented name for catalog servers; you supply it for a custom server.

OAuth

Use this when the server implements the MCP authorization profile: RFC 9728 discovery, RFC 7591 dynamic client registration, and PKCE.

Choose the server and click Authorize with MCP

Hoop discovers the provider’s authorization server, registers itself as a client, and opens the provider’s login in a browser.

Complete the login

Approve the scopes the provider asks for. Hoop writes the resulting token into the connection’s Authorization header.

If the provider has no dynamic registration

Register hoop manually with the provider, then supply the Client ID and Client Secret in the form. Whitelist this redirect URI:

https://your-hoop-gateway/api/mcp-oauth/callback

Hoop brokers the OAuth flow and freezes the resulting token onto the connection. Token refresh and per-user grants are not yet wired, so a connection whose token expires needs re-authorizing. The agent refuses MCP_AUTH=oauth at runtime rather than running an unauthenticated backend silently.

No authentication

Some servers need none. Leave the authorization panel empty and save. A stdio or client-stdio server usually falls here: it authenticates through its own environment, not an HTTP header. For a stdio server, secrets go in Headers and hoop turns them into environment variables in the child process rather than HTTP headers.

Troubleshooting

Symptom	Cause
Client shows no tools	Tool policy denied them. Denied tools are removed from the catalog by design.
`401` / `invalid proxy token`	The proxy token is wrong or expired. Re-copy it from the Connect modal.
`connection refused` on 127.0.0.1	`hoop connect` is not running, or is on a different port.
Claude Code ignores the server	The `.mcp.json` entry has a `url` but no `"type": "http"`.
Tool call fails with an auth error from the provider	The upstream credential is missing, expired, or under the wrong header name.
`client-stdio` fails to start the server	The command’s runtime is not installed on your machine, or not on your `PATH`.

MCP Gateway

What the gateway inspects and how to choose a transport.

MCP Server Catalog

Every server hoop can proxy and how each one authenticates.

Introduction

Features

Clients

Quickstart

Setup & Administration

Concepts

Integrations

Connecting an MCP Client

Two tokens, two different jobs

Which endpoint do I use?

Gateway endpoint

Local endpoint

Path A — Gateway endpoint

Path B — Local endpoint (`client-stdio`)

Configuring the upstream credential

Static token

OAuth

No authentication

Troubleshooting

See also

MCP Gateway

MCP Server Catalog

​Two tokens, two different jobs

​Which endpoint do I use?

Gateway endpoint

Local endpoint

​Path A — Gateway endpoint

​Path B — Local endpoint (client-stdio)

​Configuring the upstream credential

​Static token

​OAuth

​No authentication

​Troubleshooting

​See also

MCP Gateway

MCP Server Catalog

Two tokens, two different jobs

Which endpoint do I use?

Path A — Gateway endpoint

Path B — Local endpoint (`client-stdio`)

Configuring the upstream credential

Static token

OAuth

No authentication

Troubleshooting

See also