humans fix ai: MCP connector

Give your AI coding agent a human to call. When Claude Code, Codex, Cursor or another assistant keeps failing at something, it can ask a real, manually approved developer to help you, and follow the request through to a free 15-minute video call. You connect once, you approve every request, and nothing is charged.

From your chat to a free call

Website and setup page: https://humansfix.ai/mcp-server
Connector address: https://humansfix.ai/mcp (Streamable HTTP, sign in once with Google)
Server card: https://humansfix.ai/mcp/server-card
Official MCP Registry name: ai.humansfix/humansfix

This repository holds the documentation and examples. The server itself runs at humansfix.ai, and its source code is not published here.

What it does

AI coding agents are very good until they are not. A requirement is unclear, a change is risky, a bug will not reproduce, or you just want a person to look over what the agent built. Connect humans fix ai and your agent can do three things:

Ask a human developer. It writes a short summary of the problem.
See where your request stands and what happens next.
Answer a call time: accept the time a developer proposed, say it does not work, or propose another time for a booked call.

Your agent asks you first. Nothing reaches a developer until it has shown you the exact text and you have said yes. A developer then proposes a time for a free video call, and most problems are solved there. If more work is needed, you get one fixed price and decide whether to accept it on our website. You pay only after you approve the result.

Connect it

The first time your assistant uses the connector, it opens a page on our site: choose Continue with Google and press Allow. That is the whole sign-in. No password, no key.

Claude Code

claude mcp add --transport http humansfix https://humansfix.ai/mcp

Then run /mcp in Claude Code, choose humansfix and sign in.

Codex

codex mcp add humansfix --url https://humansfix.ai/mcp
codex mcp login humansfix

Or add this to ~/.codex/config.toml (see examples/codex-config.toml) and then run the login command:

[mcp_servers.humansfix]
url = "https://humansfix.ai/mcp"

Cursor

Add this to ~/.cursor/mcp.json, or to .cursor/mcp.json in one project, then restart Cursor (see examples/cursor-mcp.json):

{
  "mcpServers": {
    "humansfix": { "url": "https://humansfix.ai/mcp" }
  }
}

Claude on the web

The quickest way is the humans fix ai page in the Claude directory: press Add and sign in. Or add it by hand: open Settings, then Connectors, choose Add custom connector, paste https://humansfix.ai/mcp and give it a name. Under Authentication choose Sign in now. The detected "No sign-in" is not right for this connector, because calling a tool needs you to be signed in.

Any other assistant that supports remote MCP servers can use the same address. Menus and commands change from time to time, so check your assistant's own help if a step looks different.

Who answers your request

Every request is picked up by a real developer, not a bot. Developers are approved by hand before they can see any request, and the first call is free.

Let your agent suggest it

Add a short rule to your agent's instructions and it will offer a human at the moment you need one: when it has failed at the same problem several times. It still asks you first, and it never sends anything without your yes.

Tool	File	Where it goes
Claude Code	`agent-rules/CLAUDE.md`	Append to your project's `CLAUDE.md`
Codex and others	`agent-rules/AGENTS.md`	Append to `AGENTS.md`
Cursor	`rules/humansfix.mdc`	Save as `.cursor/rules/humansfix.mdc`
Claude Code skill	`skills/ask-a-human/SKILL.md`	Save as `~/.claude/skills/ask-a-human/SKILL.md`

What happens when your agent uses it

Your agent asks for your permission before it does anything.
It sends us a short summary of the problem. It must not include passwords or keys, and we refuse text that looks like one.
Your agent shows you the exact text it saved. The request stays private, and no developer sees it, until you say yes and your agent sends it. We email you a copy with a link to cancel it.
A developer proposes a time. Your agent can show it to you, and you confirm it, or say it does not work, right in the chat. You get a calendar invite and reminders by email.
The free video call. The problem is solved there, or you get one fixed price. Accepting a price, adding a card and approving the work always happen on our website, and your agent gives you the link.

What your agent can and cannot do

It can start a request for you, show where your requests stand and what happens next, accept a call time, say a time does not work, and propose another time for a booked call.

It cannot pay, accept a price, approve work, send a thank-you, report a problem, see anyone else's requests, or see anything on your account beyond your own requests.

You can disconnect it at any time in Settings, under Connected assistants. It stops working at once. We also email you whenever a new assistant is connected, so you notice one you did not expect.

What we keep, and what we never do

We keep the summary and your email, like any request made on our site.
We keep a record that you connected your assistant: its name, when you connected it, when it last used the connection, and what it may do. It lasts until you disconnect it. Its access keys are stored only in a form nobody can read back.
We never see your code, your files or your conversation with the agent. We only get what the agent chooses to send.
Nothing is published and nobody is contacted until you have read the text and said yes.
The connector never charges anything and never handles payment.
We limit how many requests can be started, and how many emails one address can receive.

For people building assistants

The connector is a stateless MCP server over Streamable HTTP that answers with JSON. It speaks the 2026-07-28 revision and also accepts the older initialize handshake from clients that use 2025-11-25, 2025-06-18, 2025-03-26 or 2024-11-05. initialize and tools/list need no token, so the tools can be discovered. Calling a tool needs one.

Signing in

A call without a valid token gets 401 with a WWW-Authenticate header whose resource_metadata points to /.well-known/oauth-protected-resource/mcp (RFC 9728). That names the authorization server, whose metadata is at /.well-known/oauth-authorization-server (RFC 8414).

OAuth 2.1 authorization code with PKCE, S256 only. Public clients: there is no client secret.
An app identifies itself either with a Client ID Metadata Document (the client_id is an https address that serves a small JSON document naming the app and its redirect addresses) or by registering at /oauth/register (RFC 7591).
Redirect addresses must be https, an address on the person's own computer (any port), or a private app scheme such as cursor://.
Send the resource parameter (RFC 8707) with the connector's address. Scopes are tasks.read and tasks.write.
Access tokens last an hour. A refresh token works once and is replaced when used. Using one a second time ends the permission.
A missing permission is 403 with insufficient_scope.

The tools

The full definitions, as the server returns them, are in docs/tool-schema.json.

Tool	Needs	Arguments	What it does
`ask_human_developer`	`tasks.write`	`summary` (required, 30 to 2000 characters, no secrets); `tool`, `availability` (optional)	Only saves a draft and returns the exact text, which the agent shows the person. Nothing reaches a developer.
`send_request`	`tasks.write`	`task_id` (required); `text` (optional, the exact saved text; nothing is sent if it differs)	Sends the draft this connection saved in the last 30 minutes, after the person said yes. A person can send a few per day, and we email them a copy with a link to cancel.
`get_task_status`	`tasks.read`	`task_id` (optional)	Returns a fixed `state`, a `next_action`, the call time in the person's own time zone, and a link to our page. It never returns text a developer wrote.
`respond_to_call_time`	`tasks.write`	`task_id`, `action` (`accept`, `decline`, `propose_other_time`), `time` (ISO 8601 with an offset, only for `propose_other_time`)	Answers a proposed call time, or proposes a new one for a booked call.

next_action is one of send_request, respond_to_call_time, person_decides_on_website, join_call, wait or none. Errors come back as tool results with isError set, so the model can correct itself. Prices, cards, approvals and tips are not part of the connector.

Check that it works

curl -s -X POST https://humansfix.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The answer lists four tools. Calling one without a token returns 401 with the sign-in pointer described above.

Contact and security

Questions and problems: [email protected]. To report a security issue, see SECURITY.md.

License

The documentation and examples in this repository are released under the MIT License. The humans fix ai service itself is operated under its own terms and privacy policy.

humans fix ai: MCP connector