Hitch

Couple your Rails app to anything that speaks MCP. Hitch is the hitch: it turns your Rails app into an authorization server implemented against the MCP 2026-07-28 authorization profile, so Claude, ChatGPT, Cursor, Grok, and any other MCP client can connect to your app's tools with OAuth handled for you.

Why

No Redis, no separate auth server, no new sign-in system. Hitch uses what your app already has: request admission counts through your configured config.cache_store, and the OAuth consent screen identifies whoever your app's own authentication says is signed in (current_user or Rails 8's Current.user).

The official Ruby MCP SDK (the mcp gem) can verify bearer tokens on a resource server, but it does not issue them, so the authorization server is left to you. Hitch is that server — on the current profile, with the authenticated endpoint and tool registry in the same gem. It is opinionated about what to implement (the 2026-07-28 MCP authorization spec) but unopinionated about whom that auth identifies — the host supplies the signed-in record.

What you get

A mountable Rails engine that bundles the pieces an authenticated MCP server needs:

• OAuth 2.1 + PKCE (S256) — the auth flow MCP clients (Claude Code, Claude.ai, Cursor, ChatGPT, etc.) use
• An authenticated /mcp endpoint — stateless POST/OPTIONS with strict host/origin admission, bounded JSON, modern MCP headers, and dispatch through the official Ruby SDK behind a private adapter
• An explicit tool registry — deny-default availability, per-principal filtering, static OAuth scope checks, and a closed result channel with schema validation and size caps
• Client ID Metadata Documents — the mechanism MCP 2026-07-28 deprecates DCR in favour of; an https URL as client_id, with the metadata fetched from it (opt-in)
• Optional Dynamic Client Registration (RFC 7591) — the generated initializer disables it; the library default stays true, so adding the gem to an existing installation never changes its behaviour silently
• Resource Indicators with audience binding (RFC 8707), discovery metadata (RFC 8414 + RFC 9728), and token revocation (RFC 7009)
• Default-deny CORS with exact host-owned origin configuration
• Generators, a test helper, and a read-only hitch:doctor for installing, testing, and diagnosing the integration

SQLite and PostgreSQL are supported on Ruby >= 3.3, < 4.1 and Rails >= 7.2, < 9. CI tests Rails 7.2/Rack 2.2/PostgreSQL, Rails 8.0/SQLite, and Rails 8.1/PostgreSQL on every push; later 8.x releases — including edge Rails — install and are expected to work, but are not covered by a release lane. Hitch requires the official Ruby MCP SDK >= 1.4, < 2.

Host models with integer, UUID, or ULID primary keys all work: access tokens store principal IDs losslessly as strings.

Quickstart

# Gemfile
gem "hitch-rails"

bundle install
bin/rails generate hitch:install   # initializer, /mcp controller, registry, routes
bin/rails db:migrate
bin/rails generate hitch:tool echo # a working, registered tool + integration test

Set resource_uri and brand_name in config/initializers/hitch.rb, and the generated tool answers tools/call — its generated test proves it over real HTTP once you point the test's one principal: line at however your tests get a signed-in user. Add --deny-default to generate a hardened tool instead: hidden, denying, and unimplemented until you fill it in. bin/rails hitch:doctor gives a read-only diagnosis of the install. bin/rails destroy hitch:tool NAME and then destroy hitch:install reverse the generators — tools first, because removing the initializer stops the app booting and destroy cannot run after that. See docs/removing.md for th

... View full README on GitHub