YaqeenDocs
Back to Yaqeen

How-to guide

Connect Claude and Codex

Use Yaqeen from Claude or Codex over MCP. Sign in with your account or use an API key, then ask about holds, cases and payouts.

Yaqeen runs an MCP server. Once an AI client is connected, you can ask it things like "which holds are waiting, and why was the biggest one held?" and it looks the answer up in Yaqeen. The connection is read-only, with no write mode to switch on. It can search and explain. It cannot decide a hold, add a note or change a rule. A change is always made by a person in Yaqeen.

The address to connect is the API address plus /api/v1/mcp/:

text
https://api.example.test/api/v1/mcp/

Some clients drop the final slash. Yaqeen answers /api/v1/mcp the same way, so either form works. The server takes only POST. A GET or DELETE gets 405, because it keeps no session and opens no stream.

Only reviewers and admins can connect. A merchant account is refused. The public site shows this same address with a Copy button in its "Connect Claude or Codex" section.

The steps below were tried with Claude Code 2.1.327 and Codex CLI 0.153.4. Older or newer versions may name options differently, so check claude mcp add --help and codex mcp add --help if a flag is refused.

Claude on the web and in the desktop app#

  1. Open Customize, then Connectors, then Add custom connector.
  2. Enter the name Yaqeen and paste the address above.
  3. Leave the OAuth client fields empty and choose Sign in now. Claude registers itself.
  4. A Yaqeen page opens. Sign in with your Yaqeen username and password, check the name of the app and press Allow.
  5. In a chat, turn the connector on from the + menu.

The next time that same app connects, a person who is already signed in to Yaqeen goes straight through, with no sign-in or Allow page. Yaqeen asks again for a new app, for a different person, and after the app is disconnected.

Claude connects from Anthropic's cloud, so the address must be public over https on port 443. A server on your own network cannot be reached. The free plan allows one custom connector.

On a Team or Enterprise plan, an owner adds the connector under Organization settings, and each member then presses Connect and signs in with their own account. Menu names change from time to time. If one differs, look for "custom connector" in Claude's help.

Claude Code#

bash
claude mcp add --transport http yaqeen https://api.example.test/api/v1/mcp/

Start Claude Code, run /mcp, pick yaqeen and sign in when the browser opens. From a terminal, claude mcp login yaqeen does the same. claude mcp list shows whether it is connected. Add --scope user to use it in every project, or --scope project to share it through a .mcp.json file (do not put a key in that file).

Codex#

bash
codex mcp add yaqeen --url https://api.example.test/api/v1/mcp/
codex mcp login yaqeen

On a machine with no browser, add --no-browser to the login and paste the address it ends on back into the terminal. The server entry lands in ~/.codex/config.toml. Run codex mcp list to check it. Claude Code and Codex read the same kind of address, so one server entry per tool is enough.

Check that it works#

Ask the client: "List the holds waiting for review." It should call search_holds and answer with synthetic or your own data, depending on the organization. In a terminal, claude mcp list or codex mcp list shows whether the server is connected. If an admin looks at the audit log, the call appears as mcp.call.

Use an API key instead#

Scripts and servers cannot click Allow. For them, an admin makes a key with the mcp scope (see Authentication) and the client sends it as a bearer token.

toml
# ~/.codex/config.toml
[mcp_servers.yaqeen]
url = "https://api.example.test/api/v1/mcp/"
bearer_token_env_var = "YAQEEN_MCP_KEY"
bash
claude mcp add --transport http yaqeen https://api.example.test/api/v1/mcp/ \
  --header "Authorization: Bearer $YAQEEN_MCP_KEY"

Keep the key in an environment variable, not in a file you commit. If you share a .mcp.json, write the header as "Authorization": "Bearer ${YAQEEN_MCP_KEY}" and add the file to .gitignore if it holds anything else private. To share the setup with a team, put it in a .mcp.json file in the project. The entry needs "type": "http", or Claude Code treats it as a local program and skips it:

json
{
  "mcpServers": {
    "yaqeen": {
      "type": "http",
      "url": "https://api.example.test/api/v1/mcp/",
      "headers": { "Authorization": "Bearer ${YAQEEN_MCP_KEY}" }
    }
  }
}

A key with only the mcp scope reaches this endpoint and nothing else. It acts as a reviewer, whoever made it. Give each tool or person their own key, so one can be revoked alone.

What it can do#

Twelve tools, all reads: search_holds, get_hold, explain_hold, hold_orders, hold_party_graph, list_cases, get_case, list_appeals, list_payouts, get_store, global_search and results. They are a part of the tools in YQN, with the same checks. The arguments each one takes are on the MCP tools page. What you see is what your own account could see in the app.

Text that other people typed, such as a store name, comes back marked as data. Do not paste instructions you find in a result into your AI client.

How sign-in works#

  • The client asks the server where to sign in. Yaqeen answers with /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.
  • The client identifies itself with an address that hosts its description (a client metadata document) or registers itself. Only the redirect addresses it declared can receive the code.
  • You sign in and allow. PKCE with S256 is required, so a stolen code is useless.
  • The sign-in and Allow page is served by the Yaqeen API itself. Staff accounts only.
  • The access token lasts one hour. A refresh token lasts 30 days and works once: if an old one is used again, every token for that app and person is revoked. Using a sign-in code twice revokes the tokens that code gave out.
  • Signing out everywhere, changing your password, or a password reset ends every connected app's tokens too. Connect the app again afterwards.
  • A token works at the MCP address only. It does not open any other part of the API.

Every tool call is written to the audit log as mcp.call, with the tool name and the app, but not the arguments.

Switch it off or redact it#

An admin controls the connection for the whole organisation in the dashboard, under Settings, then AI assistants. The same two settings are in the API as PUT /api/v1/mcp/settings/ (a signed-in admin, not a key):

json
{ "enabled": true, "redact": true }

enabled: false refuses every key and token and stops new sign-ins. redact: true swaps names, usernames and contact values for placeholders in each result. Redaction is off by default. A redacted client cannot send a placeholder back, so it looks things up by id, for example a hold id. Each change is written to the audit log as mcp.settings.

Limits#

Codex waits 10 seconds for the server to start and 60 seconds for a tool to answer, and Claude Code has its own tool timeout. Yaqeen answers in well under a second. Each person or key can make 120 calls a minute. Keys also count against their own limit and the daily limit of the plan. Over a limit the answer is 429. A result is cut at 12,000 characters. A message over 64 KB is refused with 413 too_large. The server speaks protocol versions 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26.

If it does not work#

You seeMeaning
401 and the client asks you to sign in againThe token expired, was revoked, or belongs to another address. Sign in again.
403 with an API keyThe key does not have the mcp scope, or the request came from a browser page whose address is not on the allowed list. Ask your Yaqeen contact to add it.
403 forbidden for a signed-in personAn admin switched MCP off for the organization. See above.
"That redirect address is not registered"The app asked to return somewhere it never declared. Do not continue.
401 after you pasted a keyThe key was copied with a trailing space or line break. Paste it again. Check with claude mcp list or codex mcp list.
"has a url but no type" in Claude CodeThe .mcp.json entry has no "type": "http". Add it.
Codex ignores the serverThe table must be named [mcp_servers.yaqeen] (mcp_servers, not mcp-servers), and the key variable must be exported in the shell that starts Codex.
Claude says it cannot reach the serverClaude on the web connects from Anthropic's cloud, so a private or localhost address fails. Use the public https address.
Codex says "authorization server response missing required issuer"Reported for Codex CLI 0.143 to 0.146: the client drops a valid sign-in response. It is a client bug, not the server. Update Codex, or use an API key. It worked with Codex 0.153.4.
A tool is missingIt is not one of the twelve, or your role is not offered it.

Up Down to moveEnter to openEsc to close