Connecting AI Assistants

You can connect an AI assistant such as Claude, ChatGPT, or Cursor to Hinsley through MCP, a standard way for AI assistants to connect to other apps. The assistant then works with your Hinsley data as you: it can answer questions about your analyses and forecasts, and, if you allow it, create analyses, add evidence, and create and edit questions, scenarios, drivers, and indicators.

The assistant sees only what you can see in Hinsley.

Jump to: ChatGPT, Claude Code, Codex

Before You Start

  • Your account must be on a paid plan.
  • An account admin must turn on AI Assistant Access for you. See Managing AI Assistants.
  • Your assistant must support custom connectors. Assistants may call these connectors, integrations, or MCP servers.

Connect an Assistant

  1. In your assistant, add a custom connector. Your assistant's help pages say where to find this setting. Enter this address as the server URL:
    https://www.hinsley.ai/mcp
  2. Your assistant opens Hinsley in your browser. Sign in the way you usually do. Two-factor authentication and single sign-on work as normal.
  3. Hinsley shows a page that says [assistant] wants to connect to your Hinsley account. The assistant chooses that name itself, so check the address under it: Hinsley returns you there after you connect, such as claude.ai or chatgpt.com. If you did not start this connection, or you do not recognize that address, click Cancel.
  4. To give the assistant write access, tick Write Access. Leave it unticked for read-only access. This checkbox appears only when the assistant asks for write access. If it does not appear, the connection is read-only.
  5. Click Connect. Hinsley returns you to your assistant, which can now use Hinsley. A desktop app such as Cursor opens on its own; if it does not, click Open [assistant] on the page Hinsley shows, then close the tab.

To check the connection, ask your assistant which Hinsley analyses it can see.

To change an assistant from read-only to write access, or back, disconnect it and connect it again.

A connection lasts 90 days. It ends sooner if the assistant does not use Hinsley for 30 days. When it ends, connect the assistant again.

ChatGPT

  1. In ChatGPT on the web, open Plugins.
  2. Click the plus button, then click Add custom MCP server.
  3. Enter a name, such as Hinsley. Under Connection, enter this Server URL:
    https://www.hinsley.ai/mcp
  4. For authentication, select OAuth.
  5. Read the warning, click I understand and want to continue, and then click Create as a plugin.
  6. Install the plugin. When ChatGPT opens Hinsley, sign in and connect as described above.

To use Hinsley in a conversation, type @ in the message box and select the plugin. ChatGPT asks you to confirm each change before the assistant makes it. If Add custom MCP server does not appear, your ChatGPT workspace may not allow custom servers. Ask your ChatGPT workspace admin.

Claude Code

Add Hinsley from your terminal:

claude mcp add --transport http hinsley https://www.hinsley.ai/mcp

Then run /mcp in Claude Code and select hinsley. Claude Code opens Hinsley in your browser, where you sign in and connect as described above.

Codex

Add Hinsley from your terminal, then sign in:

codex mcp add hinsley --url https://www.hinsley.ai/mcp
codex mcp login hinsley

Codex opens Hinsley in your browser, where you sign in and connect as described above. On a computer without a browser, run codex mcp login hinsley --no-browser, open the address that Codex prints, and paste the address you land on back into the terminal.

To check the connection, run codex mcp list, or type /mcp in Codex.

In the Codex IDE extension, open the gear menu, select MCP servers, and then select Add server. Enter hinsley as the name, choose Streamable HTTP, and enter the server URL above. Save, then select Restart extension. The Codex desktop app has the same setting under Settings > MCP servers. The CLI, the extension, and the desktop app share one configuration.

Connect With an API Token

Some tools cannot open a browser to sign in, but can send an access token instead. For those tools, create an API token:

  1. Click your avatar, then My Account.
  2. Click API Tokens in the sidebar, then create a token.
  3. Tick AI assistant (MCP) only. To give the tool write access, also tick Write access.
  4. Copy the token. Hinsley shows it only once.
  5. Give the token to your tool as a bearer token. Replace YOUR_TOKEN with your token.
    • Claude Code:
      claude mcp add --transport http hinsley https://www.hinsley.ai/mcp --header "Authorization: Bearer YOUR_TOKEN"
    • Codex: put the token in an environment variable, such as HINSLEY_TOKEN, and add this to ~/.codex/config.toml:
      [mcp_servers.hinsley]
      url = "https://www.hinsley.ai/mcp"
      bearer_token_env_var = "HINSLEY_TOKEN"

The API Tokens page appears only when your account allows API access. A token connection does not appear on Connected Apps. To stop it, revoke the token on the API Tokens page. Hinsley also revokes these tokens when AI Assistant Access is set to Disabled, or when you lose API access.

What an Assistant Can Do

With Read Access

Every connected assistant can read:

  • Your analyses, with their scenario sets, scenarios, and current likelihoods
  • Forecasting questions, their current forecasts, and their forecast history with rationales
  • Decompositions, with their drivers and indicators
  • The evidence collected for an analysis, which it can search and read
  • What changed recently: forecast moves, new questions, and new evidence

The assistant does not receive the name or email address of anyone in Hinsley, including you. Forecasters and collaborators appear without their names, and a person mentioned or cited in a forecast rationale is replaced with a placeholder. Other names that people wrote into text, such as in evidence, are passed on as written.

With Write Access

An assistant with write access can also:

  • Create an analysis from a topic, with its purpose, scope, audience, and time horizon
  • Add evidence to an analysis from a web URL or text with a title
  • Create forecasting questions and edit their text, dates, and answer options, which includes removing an answer option
  • Add scenarios to a scenario set and edit them
  • Add drivers and indicators to a decomposition
  • Link drivers to scenarios

Changes appear in Hinsley under your name, the same as changes you make yourself. The assistant cannot make a change that you could not make in Hinsley. It cannot delete questions, scenarios, drivers, or indicators.

A new analysis starts initial AI research by default, using your account's default evidence sources. To bring research from your conversation into Hinsley, ask the assistant to create the analysis without starting research, then add the evidence and scenarios you discussed. Your account's usual analysis limits apply either way.

When the assistant adds evidence, Hinsley fetches and processes it in the background. The assistant can check its fetch status and read it when the content is available. Text supplied in the conversation is saved as private evidence in the analysis's account. The assistant can add up to 200,000 characters of text at a time; file uploads through the connector are not supported.

Some changes start AI work in Hinsley, the same as when you make them yourself. Initial research, evidence processing, a new question's initial AI forecast, and indicator generation count toward your account's AI usage. The assistant can request a first AI forecast when creating a question and can choose whether to generate indicators when adding a driver.

Where Your Data Goes

Everything the assistant reads from Hinsley goes to that assistant's AI provider, for example Anthropic for Claude or OpenAI for ChatGPT. That provider's terms and data policies apply to it.

See and Disconnect Your Assistants

  1. Click your avatar, then My Account.
  2. Click Connected Apps in the sidebar.

The page lists each connected assistant with the address it returns to, its access level, Read only or Read and write, and when it was last active. Click Disconnect to stop an assistant at once.

Keep Assistants Away From One Analysis

If you created an analysis, you can block every AI assistant from it:

  1. Open the analysis and click Settings.
  2. Under AI Assistants, click Block AI assistants, then confirm.

The analysis, and its questions, scenarios, drivers, and evidence, are then hidden from every assistant at once, including assistants that are already connected and the assistants of collaborators. To allow assistants again, click Allow AI assistants. If you did not create the analysis, ask its creator or an account admin.

Troubleshooting

"AI assistant access is not available"

Hinsley shows this page when your account does not allow you to connect an assistant. An account admin must turn on AI Assistant Access, or set it to Everyone if it is set to Admins only. Click Return to [assistant] to tell the assistant that the connection did not go ahead, then ask an account admin to turn on access for you.

"This connection request is not valid"

The assistant sent a request that Hinsley cannot accept. Remove the connector from your assistant and add it again. If the problem continues, contact your assistant's support team.

The assistant stopped working

Check that the assistant still appears on your Connected Apps page, and that AI assistant access is still on for your account. A connection also ends after 90 days, or after 30 days without use. Reconnect the assistant from its own settings.

"This assistant is not allowed"

Your account allows only some assistants, and this one is not on the list. Ask an account admin to add it, and tell them which assistant you use, such as Claude at claude.ai or Claude Code on your computer. Admins can see Limit Which Assistants Can Connect.