MCP Server Setup

What is the CoreStory MCP Server?

The CoreStory MCP (Model Context Protocol) server enables AI coding assistants to directly access your CoreStory project data—including PRDs, technical specifications, codebase conversations, and project architecture—without manual copy-pasting or context switching. What you can do with it:

Query project documentation and requirements directly from your AI assistant
Access conversation history and codebase insights
Generate and retrieve PRD/TechSpec sections
Search a project’s code index directly
Create and manage project conversations
Maintain context across multiple coding sessions

Supported AI Tools: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (GitHub Copilot), and any other client that speaks remote MCP over HTTP.

How Connecting Works

Each CoreStory organization has its own MCP URL. You copy that URL into your AI client, and the first time the client connects, it opens your browser to sign in to CoreStory. There is no token to copy, paste, or store.

https://app.corestory.ai/mcp/{your-org-slug}-{org-id}

Two things to know about this URL:

It is scoped to one organization. The URL identifies the org, not you. Everyone in the org uses the same URL, and it never spans multiple orgs. To connect a different org, switch orgs using the org switcher and copy that org’s URL.
It is not a secret, but treat it as private anyway. Access is granted by your browser sign-in, not by the URL. Someone who has the URL but no CoreStory account in that org cannot read anything.

Sign-in is handled by CoreStory’s identity provider (Clerk) at clerk.corestory.ai using standard OAuth. Your AI client receives a short-lived access token; CoreStory never sees your password, and no long-lived credential is written to your config files.

Previously, connecting required generating a long-lived mcp_... token and pasting it into an Authorization header. That flow is deprecated. Existing tokens keep working until they expire — see Legacy MCP Tokens.

Prerequisites

A CoreStory account with access to your organization’s workspace
At least one ingested project in that organization
One of the supported AI coding tools installed

Step 1: Copy Your MCP URL

Go to app.corestory.ai/settings
Under Organization Related, open IDE Integrations
Confirm the org name shown above the section is the one you want to connect
Click Copy next to Your MCP URL

The panel also has an Add it to your client tab strip with the exact config for Claude Code, Claude Desktop, Cursor, and Windsurf — pre-filled with your org’s URL. The instructions below match those tabs.

Step 2: Add It to Your Client

Claude Code

Add the server — in your terminal, run:

claude mcp add --transport http corestory https://app.corestory.ai/mcp/your-org-slug-123456789

Add --scope user to make the server available across all your projects rather than just the current one.

Open Claude Code and run /mcp
Select corestory → Authenticate. Your browser opens for sign-in.
Approve access. Claude Code is now connected.

Run /mcp again at any time to check connection status or re-authenticate.

Claude Desktop

Remote MCP servers are added through the Claude Desktop UI, not through claude_desktop_config.json.

Open Settings → Connectors
Click Add custom connector
Paste your MCP URL. Leave Advanced settings blank.
Click Add — your browser opens for sign-in and consent.

On Claude free plans, only one custom connector is allowed at a time.

Cursor

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "corestory": {
      "url": "https://app.corestory.ai/mcp/your-org-slug-123456789"
    }
  }
}

Save the file and restart Cursor. Cursor opens your browser to sign in on first use.

No headers block is needed. If you are migrating from the token flow, delete the old Authorization header entirely — leaving it in place makes Cursor send the stale token instead of starting the browser sign-in.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json, either directly or via Cascade → Settings → MCP Servers:

{
  "mcpServers": {
    "corestory": {
      "serverUrl": "https://app.corestory.ai/mcp/your-org-slug-123456789"
    }
  }
}

Windsurf uses serverUrl for remote servers, not url. Using url here will fail to connect.

Save the file, then click Refresh in the MCP Servers panel. Windsurf opens your browser to sign in on first use.

Other MCP Clients

Any client with remote MCP + OAuth support connects the same way: give it your MCP URL as an HTTP (streamable) remote server, with no authorization header, and complete the browser sign-in it prompts for. This covers VS Code / GitHub Copilot’s MCP support and similar clients. If your client can reach a remote MCP server but cannot perform the OAuth browser flow, it needs a legacy token instead — see below.

Legacy MCP Tokens (Deprecated)

Long-lived mcp_{token_id}.{jwt} tokens are deprecated. Prefer the URL + OAuth flow above.

Existing tokens keep working until they expire. Nothing breaks today.
New token creation is discouraged. Use it only for clients that cannot do the browser OAuth flow, or for headless/CI use.
Manage tokens under Settings → IDE Integrations → Legacy tokens, which lists each token’s name, status, expiry, and last-used date, with a Revoke action.

If you still need a token, send it as a bearer header against the same URL:

{
  "mcpServers": {
    "corestory": {
      "url": "https://app.corestory.ai/mcp/your-org-slug-123456789",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}

Migrating off a token: remove the headers block from your client config (or re-run claude mcp add without --header), reconnect, complete the browser sign-in, then revoke the old token in Settings.

Available Tools

Once connected, these tools are available to your AI assistant:

Tool	Description
`list_projects`	List all projects in your organization with their ingestion status
`get_project_prd`	Retrieve a project’s Product Requirements Document
`get_project_techspec`	Retrieve a project’s Technical Specification
`list_conversations`	List all conversations for a project
`get_conversation`	Get a conversation’s details and message history
`create_conversation`	Create a new conversation in a project
`rename_conversation`	Rename an existing conversation
`send_message`	Send a message to a conversation and get an AI response
`refine_document_definition`	Build and validate a custom document definition
`generate_document`	Start generation of a custom document
`get_document_generation_result`	Poll a document generation run for results
`semantic_search`	Semantic-search a project’s code index and return ranked chunks
`describe_index`	List the file paths and filterable metadata keys in a project’s index
`filter_chunks`	Fetch index chunks by metadata filter alone, with no semantic ranking

get_project_prd and get_project_techspec support sections_only, sections, limit, and offset. For large documents, discover the section list first and then request only the sections you need.

Your AI assistant can use these automatically when you ask questions about your CoreStory projects.

Testing Your Connection

Ask your AI assistant:

Can you list my CoreStory projects?

The assistant should call list_projects and show the projects in your organization.

tools/list is answered without authentication, so seeing the tool list is not proof that sign-in succeeded. Calling a tool is. If tools appear but every call fails, you are connected but not authenticated.

Pairing CoreStory With Other MCP Servers

Your coding agent can hold several MCP servers at once, and they compose well: each one contributes a different kind of context, and the agent decides which to consult. CoreStory contributes code intelligence — what the system does today and why.

These servers do not talk to each other. Each connects independently to your agent, and the agent is what combines them. Adding a second server never gives it access to your CoreStory data.

Evermuse

Evermuse is a customer intelligence platform — it collects and synthesizes what your customers are actually saying. Paired with CoreStory, an agent can answer questions that neither product can answer alone: what customers are asking for (Evermuse) checked against what the code currently does (CoreStory). Evermuse’s MCP server uses OAuth 2.1 with no API key, so it connects the same way CoreStory does. Evermuse MCP endpoint:

https://api.evermuse.com/api/mcp

Claude Code — add both servers, then authenticate each via /mcp:

claude mcp add --transport http corestory https://app.corestory.ai/mcp/your-org-slug-123456789
claude mcp add --transport http evermuse https://api.evermuse.com/api/mcp

Cursor — both entries live in the same ~/.cursor/mcp.json:

{
  "mcpServers": {
    "corestory": {
      "url": "https://app.corestory.ai/mcp/your-org-slug-123456789"
    },
    "evermuse": {
      "url": "https://api.evermuse.com/api/mcp"
    }
  }
}

You will sign in twice — once to CoreStory, once to Evermuse — since each server authenticates against its own account. Once both are connected, you can ask things like:

Pull the top onboarding complaints from Evermuse, then use CoreStory
to show me which parts of the signup flow those complaints touch.

For current Evermuse setup steps — including Claude Desktop, ChatGPT, and Codex — see Evermuse’s own MCP integration page. Their configuration is theirs to change; treat that page as the source of truth for the Evermuse side.

Troubleshooting

”Missing or invalid Authorization header”

You are reaching the server but have not signed in.

In Claude Code, run /mcp, select corestory, and choose Authenticate
In other clients, remove and re-add the server to re-trigger the browser flow
Check that no stale Authorization header is left in your config — it suppresses the OAuth flow
Complete the browser consent screen; closing it early leaves the client unauthenticated

The Browser Never Opens

Confirm your client supports remote MCP with OAuth, and that it is up to date
Check the client’s MCP logs for a sign-in URL you can open manually
If the client genuinely cannot do the browser flow, use a legacy token instead

Connected, But No Projects Listed

Verify the URL is for the org you expect — the slug in the URL is the org
Confirm that org actually has ingested projects
If you belong to multiple orgs, switch orgs in the app and copy that org’s URL

Tools Not Available At All

Restart your AI tool completely
Verify the server appears in the tool’s connected-servers list
Check your configuration file is valid JSON — and that Windsurf uses serverUrl, not url
Look for errors in the tool’s developer console or MCP logs

Slow or Timeout Responses

For large PRDs/TechSpecs, request specific sections rather than the whole document
generate_document is long-running — submit it, then poll get_document_generation_result
Increase timeout settings in your AI tool if it allows it

Security Notes

No credentials in config files — the OAuth flow stores a short-lived token in your client’s own credential store, not in the JSON you commit
Access follows your account — losing access to the org immediately ends MCP access; there is no lingering token to revoke
Revoke legacy tokens you no longer use — Settings → IDE Integrations → Legacy tokens
One org per connection — if you need two orgs, add two servers under different names

Support

CoreStory Documentation: https://docs.corestory.ai
MCP Protocol Spec: https://modelcontextprotocol.io
Support Email: support@corestory.ai

Last Updated: August 2026

About CoreStory

Getting Started

Product

What is the CoreStory MCP Server?

How Connecting Works

Prerequisites

Step 1: Copy Your MCP URL

Step 2: Add It to Your Client

Claude Code

Claude Desktop

Cursor

Windsurf

Other MCP Clients

Legacy MCP Tokens (Deprecated)

Available Tools

Testing Your Connection

Pairing CoreStory With Other MCP Servers

Evermuse

Troubleshooting

”Missing or invalid Authorization header”

The Browser Never Opens

Connected, But No Projects Listed

Tools Not Available At All

Slow or Timeout Responses

Security Notes

Support

​What is the CoreStory MCP Server?

​How Connecting Works

​Prerequisites

​Step 1: Copy Your MCP URL

​Step 2: Add It to Your Client

​Claude Code

​Claude Desktop

​Cursor

​Windsurf

​Other MCP Clients

​Legacy MCP Tokens (Deprecated)

​Available Tools

​Testing Your Connection

​Pairing CoreStory With Other MCP Servers

​Evermuse

​Troubleshooting

​”Missing or invalid Authorization header”

​The Browser Never Opens

​Connected, But No Projects Listed

​Tools Not Available At All

​Slow or Timeout Responses

​Security Notes

​Support

What is the CoreStory MCP Server?

How Connecting Works

Prerequisites

Step 1: Copy Your MCP URL

Step 2: Add It to Your Client

Claude Code

Claude Desktop

Cursor

Windsurf

Other MCP Clients

Legacy MCP Tokens (Deprecated)

Available Tools

Testing Your Connection

Pairing CoreStory With Other MCP Servers

Evermuse

Troubleshooting

”Missing or invalid Authorization header”

The Browser Never Opens

Connected, But No Projects Listed

Tools Not Available At All

Slow or Timeout Responses

Security Notes

Support