Connect Askance to your agent

Project-scoped MCP config, plus a Skill so the agent reaches for Askance on its own.

1. Fastest: paste this to your agent

   Your agent can do the whole setup itself — and unlike a copied snippet it can see which OS and client it is in, so it picks a place for the key that actually survives a restart. Paste this, with your key from Settings, and let it work. The manual steps below are the fallback.

   Set up Askance in this project.
   
   Fetch https://www.askance.app/install.md and follow it exactly, for whichever
   client and OS you are running in.
   
   My key is: <paste your key here>
   
   Keep the connection specific to THIS project, and check for an existing Askance
   connection first — if there is already one (for a different Askance project), name
   this one after the project rather than reusing "Askance".
   
   Store the key where it persists across restarts, and never in a file that gets
   committed — check .gitignore before writing anything, and do not echo the key
   back to me.

2. Or add it yourself: one command, no environment variable

   Defaults to --scope local: recorded against THIS project directory and private to you, so the key persists across restarts with no environment variable to set and nothing secret can be committed. Run `claude mcp list` first — if an Askance connection already exists for a different Askance project, name this one after the project (Askance-YourProject) so calls and errors say which one they came from. Renaming changes the tool ids to mcp__Askance_YourProject__*, so only do it when there is genuinely more than one.

   claude mcp add --transport http Askance https://mcp.askance.app/mcp   --header "Authorization: Bearer ask_..."

3. Only if your TEAM shares the config: .mcp.json

   Commit this at the root of your repo. Every teammate who opens the project gets the same connection, and the key stays in their environment rather than in the file. Name the server after the project when it is shared like this — a teammate seeing a bare "askance" cannot tell which Askance project it reaches, and anyone who works on two of your repos ends up with two connections answering to the same name.

   .mcp.json

   {
     "mcpServers": {
       "askance": {
         "type": "http",
         "url": "https://mcp.askance.app/mcp",
         "headers": {
           "Authorization": "Bearer ${ASKANCE_KEY}"
         }
       }
     }
   }

4. Add a Skill so the agent knows when to ask

   Connecting the server gives Claude Code tools it can call, but nothing that prompts it to. A Skill is model-invoked — Claude reads the description and reaches for it when the situation matches — which is what turns Askance from an available tool into one that actually gets used.

   .claude/skills/askance/SKILL.md

   ---
   name: askance
   description: Ask a human subject-matter expert when a question cannot be answered from the codebase — business rules, product decisions, integration details. Use whenever you would otherwise guess or stall.
   ---
   
   When you hit a question you cannot answer from the codebase,
   the docs, or the conversation — a business rule, a product decision, an
   integration detail, anything held by a person rather than written down —
   do NOT guess and do NOT stop and wait for the user.
   
   1. Call Askance's `search_records` first. It may already be answered.
   2. If not, call `ask_question` with the full context, the options you can
      see, and the one you recommend.
   3. Carry on with other work immediately — do not sit and wait for the answer.
      Answers can take hours or days. If the question genuinely gates everything
      else, say so in the question so a human knows it is urgent.
   4. Call `check_questions` at the start of a session and between tasks to
      pick up answers that have landed.

5. Set your key so it persists

   Your key comes from Settings once you have signed in. Set it so it SURVIVES A RESTART — a bare `export` in a terminal lasts only for that terminal, and an editor you launched from a Start menu or Dock never sees it at all. That is the single most common reason a connection works once and is gone the next day.

   # macOS / Linux — append to ~/.zshrc (or ~/.bashrc), then open a NEW terminal
   echo 'export ASKANCE_KEY="ask_..."' >> ~/.zshrc
   
   # Windows PowerShell — persists for your user account
   [Environment]::SetEnvironmentVariable('ASKANCE_KEY', 'ask_...', 'User')
   
   # Then FULLY restart the app (not just the window) and check it resolved:
   #   macOS/Linux:  printenv ASKANCE_KEY
   #   PowerShell:   $env:ASKANCE_KEY
   
   # in Claude Code, after restarting:
   /mcp          # askance should be listed as connected, not failed

MCP config under .cursor, plus an always-applied rule carrying the standing instruction.

1. Fastest: paste this to your agent

   Your agent can do the whole setup itself — and unlike a copied snippet it can see which OS and client it is in, so it picks a place for the key that actually survives a restart. Paste this, with your key from Settings, and let it work. The manual steps below are the fallback.

   Set up Askance in this project.
   
   Fetch https://www.askance.app/install.md and follow it exactly, for whichever
   client and OS you are running in.
   
   My key is: <paste your key here>
   
   Keep the connection specific to THIS project, and check for an existing Askance
   connection first — if there is already one (for a different Askance project), name
   this one after the project rather than reusing "Askance".
   
   Store the key where it persists across restarts, and never in a file that gets
   committed — check .gitignore before writing anything, and do not echo the key
   back to me.

2. Add the MCP server

   Cursor interpolates ${env:NAME} inside url and headers, so the key is read from your environment rather than committed.

   .cursor/mcp.json

   {
     "mcpServers": {
       "askance": {
         "url": "https://mcp.askance.app/mcp",
         "headers": {
           "Authorization": "Bearer ${env:ASKANCE_KEY}"
         }
       }
     }
   }

3. Add an always-applied rule

   Cursor has no Skills equivalent. A project rule with alwaysApply is the closest thing — it is prepended to context for every request in this project, so the agent is always aware Askance is an option.

   .cursor/rules/askance.mdc

   ---
   description: Ask a human expert instead of guessing
   alwaysApply: true
   ---
   
   When you hit a question you cannot answer from the codebase,
   the docs, or the conversation — a business rule, a product decision, an
   integration detail, anything held by a person rather than written down —
   do NOT guess and do NOT stop and wait for the user.
   
   1. Call Askance's `search_records` first. It may already be answered.
   2. If not, call `ask_question` with the full context, the options you can
      see, and the one you recommend.
   3. Carry on with other work immediately — do not sit and wait for the answer.
      Answers can take hours or days. If the question genuinely gates everything
      else, say so in the question so a human knows it is urgent.
   4. Call `check_questions` at the start of a session and between tasks to
      pick up answers that have landed.

4. Set your key so it persists

   Your key comes from Settings once you have signed in. Set it so it SURVIVES A RESTART — a bare `export` in a terminal lasts only for that terminal, and an editor you launched from a Start menu or Dock never sees it at all. That is the single most common reason a connection works once and is gone the next day.

   # macOS / Linux — append to ~/.zshrc (or ~/.bashrc), then open a NEW terminal
   echo 'export ASKANCE_KEY="ask_..."' >> ~/.zshrc
   
   # Windows PowerShell — persists for your user account
   [Environment]::SetEnvironmentVariable('ASKANCE_KEY', 'ask_...', 'User')
   
   # Then FULLY restart the app (not just the window) and check it resolved:
   #   macOS/Linux:  printenv ASKANCE_KEY
   #   PowerShell:   $env:ASKANCE_KEY

TOML config that names an environment variable, plus AGENTS.md for the standing instruction.

1. Fastest: paste this to your agent

   Your agent can do the whole setup itself — and unlike a copied snippet it can see which OS and client it is in, so it picks a place for the key that actually survives a restart. Paste this, with your key from Settings, and let it work. The manual steps below are the fallback.

   Set up Askance in this project.
   
   Fetch https://www.askance.app/install.md and follow it exactly, for whichever
   client and OS you are running in.
   
   My key is: <paste your key here>
   
   Keep the connection specific to THIS project, and check for an existing Askance
   connection first — if there is already one (for a different Askance project), name
   this one after the project rather than reusing "Askance".
   
   Store the key where it persists across restarts, and never in a file that gets
   committed — check .gitignore before writing anything, and do not echo the key
   back to me.

2. Add the MCP server

   Codex takes a different shape from the others: rather than a headers block, it takes the NAME of an environment variable and builds the Authorization header itself. Project config wins over the global ~/.codex/config.toml.

   .codex/config.toml

   [mcp_servers.askance]
   url = "https://mcp.askance.app/mcp"
   bearer_token_env_var = "ASKANCE_KEY"

3. Add the standing instruction to AGENTS.md

   Codex reads AGENTS.md from the repo automatically. Append this so it knows Askance exists and when to reach for it.

   AGENTS.md

   ## Asking a human
   
   When you hit a question you cannot answer from the codebase,
   the docs, or the conversation — a business rule, a product decision, an
   integration detail, anything held by a person rather than written down —
   do NOT guess and do NOT stop and wait for the user.
   
   1. Call Askance's `search_records` first. It may already be answered.
   2. If not, call `ask_question` with the full context, the options you can
      see, and the one you recommend.
   3. Carry on with other work immediately — do not sit and wait for the answer.
      Answers can take hours or days. If the question genuinely gates everything
      else, say so in the question so a human knows it is urgent.
   4. Call `check_questions` at the start of a session and between tasks to
      pick up answers that have landed.

4. Set your key so it persists

   Codex reads the key from the variable named above, so nothing secret goes in the config file — which also means the variable has to outlive the terminal you set it in. Your key comes from Settings once you have signed in. Set it so it SURVIVES A RESTART — a bare `export` in a terminal lasts only for that terminal, and an editor you launched from a Start menu or Dock never sees it at all. That is the single most common reason a connection works once and is gone the next day.

   # macOS / Linux — append to ~/.zshrc (or ~/.bashrc), then open a NEW terminal
   echo 'export ASKANCE_KEY="ask_..."' >> ~/.zshrc
   
   # Windows PowerShell — persists for your user account
   [Environment]::SetEnvironmentVariable('ASKANCE_KEY', 'ask_...', 'User')
   
   # Then FULLY restart the app (not just the window) and check it resolved:
   #   macOS/Linux:  printenv ASKANCE_KEY
   #   PowerShell:   $env:ASKANCE_KEY

Askance is a standard streamable-HTTP MCP server with bearer auth — no Askance-specific client needed.

1. Fastest: paste this to your agent

   Your agent can do the whole setup itself — and unlike a copied snippet it can see which OS and client it is in, so it picks a place for the key that actually survives a restart. Paste this, with your key from Settings, and let it work. The manual steps below are the fallback.

   Set up Askance in this project.
   
   Fetch https://www.askance.app/install.md and follow it exactly, for whichever
   client and OS you are running in.
   
   My key is: <paste your key here>
   
   Keep the connection specific to THIS project, and check for an existing Askance
   connection first — if there is already one (for a different Askance project), name
   this one after the project rather than reusing "Askance".
   
   Store the key where it persists across restarts, and never in a file that gets
   committed — check .gitignore before writing anything, and do not echo the key
   back to me.

2. Point your client at the server

   There is no SDK to install and no npm package required. Askance is a remote MCP server: any client that speaks streamable HTTP and can send an Authorization header can connect. Most take a shape close to this.

   mcp.json

   {
     "mcpServers": {
       "askance": {
         "url": "https://mcp.askance.app/mcp",
         "headers": {
           "Authorization": "Bearer ask_..."
         }
       }
     }
   }

3. Load the standing instruction

   Askance exposes an MCP prompt called askance_workflow containing the full guidance — when to search versus ask, how to poll without blocking, and how to work the Directions and Corrections. If your client surfaces MCP prompts, load it once per session. If it supports an always-on instruction file instead, paste the text below into it.

   standing instruction

   When you hit a question you cannot answer from the codebase,
   the docs, or the conversation — a business rule, a product decision, an
   integration detail, anything held by a person rather than written down —
   do NOT guess and do NOT stop and wait for the user.
   
   1. Call Askance's `search_records` first. It may already be answered.
   2. If not, call `ask_question` with the full context, the options you can
      see, and the one you recommend.
   3. Carry on with other work immediately — do not sit and wait for the answer.
      Answers can take hours or days. If the question genuinely gates everything
      else, say so in the question so a human knows it is urgent.
   4. Call `check_questions` at the start of a session and between tasks to
      pick up answers that have landed.