Remote MCP server starter for Railway

A Model Context Protocol server your agent connects to over the network, with a working OAuth 2.1 authorization server in front of it. Deploy it, add the URL to your client, type a password once — the client registers itself and gets a token.

Why this exists

The catalogue has plenty of MCP servers, and almost all of them wrap somebody else's SaaS: a server for Whoop, one for Meta Ads, one for a CRM. If what you want is to expose your own data — an internal API, a database, a document store — there is nothing to start from.

The hard part was never the tools. It is everything around them:

• Transport. Streamable HTTP replaced SSE, and stateless is the shape that survives more than one replica. Sessions in memory mean sticky routing.

• Authorization. The MCP spec puts OAuth 2.1 in the required path: PKCE, dynamic client registration, protected-resource metadata under RFC 9728, resource indicators under RFC 8707. Clients will not connect without it.

• Storage. Codes and tokens have to outlive the process that issued them, or every deploy logs everyone out and a second replica rejects the first one's tokens.

This starter does all three, and leaves you three example tools to replace.

Related MCP server: mcp-production-kit

What you get

Three example tools — add_note, search_notes, whoami — are backed by a real table. They exist so a fresh deployment can be proven end to end, and so you have a working handler to copy.

Deploy

Two services: this repository and a Postgres. The template wires them together and generates the password for you.

After the first deploy, open the service URL — the page shows the exact URL to paste into your client.

Add it to a client

Use https://<your-domain>/mcp. The client discovers the authorization server, registers itself, opens the login page in a browser, and stores the token it gets back. There is nothing to configure on the client side and no API key to copy around.

For clients that speak stdio only, npx mcp-remote https://<your-domain>/mcp bridges the two.

Prove it works

npx tsx scripts/verify-oauth-flow.ts https://<your-domain> '<the password>'

The script walks the whole path a real client walks — discovery, registration, PKCE, login, token exchange, tools/call — and also checks the parts that are supposed to fail: an unauthenticated call, a wrong password, a replayed authorization code, a reused refresh token, weak PKCE, unsafe redirect URIs, unknown scopes, script injected into the login page, and a burst of parallel password guesses. That last check locks the addresses it used out of login for 15 minutes, so against a remote server it only runs with VERIFY_LOCKOUT=1.

Write your own tools

src/tools.ts is the whole surface. Add a registerTool call with a Zod input schema and a handler; the token that authorized the call arrives as auth, so you can key data by auth.clientId or check auth.scopes per tool.

The example tools are deliberately backed by Postgres rather than returning canned strings — that is what makes a first deploy prove the write path.

How the security is set up

• Tokens are stored hashed (SHA-256). A database dump does not hand anyone a working token.

• Authorization codes are single-use, enforced by marking them consumed in the same statement that reads them, so a replay finds nothing to update — not by a check-then-write that two concurrent requests can both pass.

• PKCE is required (S256); the code challenge is bound to the code.

• Login is rate limited — 10 attempts per address per 15 minutes, counted in Postgres so the limit holds across replicas rather than per process. The address is the one Railway's proxy reports (trust proxy defaults to one hop, see TRUST_PROXY_HOPS), so a client cannot pick its own with an X-Forwarded-For header. Registration, authorize, token and revoke have their own per-address limits.

• Passwords are compared in constant time, over hashes, so neither content nor length leaks through timing.

• Refresh rotates, and reuse revokes the grant: using a refresh token revokes it and issues a new pair. A refresh can narrow its scopes, never widen them. Presenting a refresh token that was already rotated, or an authorization code that was already used, revokes every token issued under that authorization, because it means a copy leaked. Revoking a refresh token also revokes its access tokens.

• The login page names the client and where the code goes. Anyone can register a client under any name, so the page shows the name as unverified plus the redirect host, and asks for a confirmation tick when that host is not your own machine. Check the host before you type the password. The page is served with a strict Content-Security-Policy (no scripts, no framing), all dynamic values are escaped, and the request id is validated before it is used.

• Registration is validated: redirect URIs must be https, http on localhost/127.0.0.1/[::1], or a reverse-domain app scheme such as com.example.app:; fragments are refused. Requested scopes must be in the supported set (mcp:tools); unknown scopes get invalid_scope. A client that registers without token_endpoint_auth_method is told client_secret_post.

• Login attempts are counted atomically before the password is checked, so a burst of parallel guesses cannot exceed the limit. IPv6 clients share one budget per /64.

One honest note: client secrets issued by dynamic registration are stored as issued, because client authentication compares them directly. MCP clients normally register as public clients and rely on PKCE, which is the path this server expects.

Configuration

Upgrading

The schema changes are additive and run on startup (one replica migrates while the others wait): grant_id on codes and tokens, rotated_at on tokens. Tokens issued by the previous version keep working. A refresh token from before the upgrade joins a grant at its first rotation; one that was already rotated before the upgrade is rejected as before, but its reuse cannot revoke a family that was never recorded. Rolling back to the previous version is safe, the old code ignores the new columns.

Run locally

npm ci
cp .env.example .env
npm run dev

Plain HTTP is fine for the issuer on localhost, which is exactly where you will be running it; anywhere else use HTTPS.

Using an external identity provider

This server is its own authorization server, which is what makes it deploy in one click. If you already run Keycloak, Auth0 or Zitadel, delete src/authorization-server.ts, src/oauth-provider.ts and src/login.ts, point mcpAuthMetadataRouter at your issuer's metadata, and give requireBearerAuth a verifier for its tokens; the tools and transport stay as they are.

A note on versions

Built on the MCP TypeScript SDK v2: @modelcontextprotocol/server 2.3.0 for the server and Streamable HTTP handler, @modelcontextprotocol/express and @modelcontextprotocol/node for the Express integration and bearer-token check. The v2 SDK is a resource-server library: it verifies tokens and publishes metadata but no longer ships an authorization server (the v1 helpers survive only in the deprecated @modelcontextprotocol/server-legacy, which this starter does not use). The OAuth endpoints — /register, /authorize, /token, /revoke and the metadata document — are therefore implemented in src/authorization-server.ts on top of the same Postgres schema, with the same request and error formats as before, so existing deployments and registered clients keep working.

License

MIT