MCP Server Setup - CoreStory Docs

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
Create and manage project conversations
Maintain context across multiple coding sessions

Supported AI Tools: Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, Devin, Factory.ai

Prerequisites

CoreStory account with active projects
Access to your organization’s CoreStory workspace
One of the supported AI coding tools installed

Quick Setup (Dashboard)

The fastest way to connect your IDE to CoreStory is through the setup wizard in the CoreStory Dashboard at preview.corestory.ai/settings.

Step 1: Open IDE Integrations

Go to Settings → scroll down to the IDE Integrations section
Click the Configure button under “MCP Connection”

This launches the guided setup wizard.

Step 2: Generate an MCP Token

Enter a Token Name (optional but recommended — e.g., “MacBook Pro”, “Work Desktop”) to help you identify the token later
Click Generate MCP Token
Copy the token immediately — it will not be shown again

The token is displayed only once. Copy it now and store it securely. If you lose it, you’ll need to generate a new one.

Step 3: Select Your IDE

Choose the IDE you want to connect to CoreStory:

VS Code
Cursor
Windsurf
Other MCP Tools (for Claude Desktop, Devin, Factory.ai, etc.)

Step 4: Configure Your IDE

The wizard provides IDE-specific setup instructions. For example, for VS Code:

Open VS Code Settings (Cmd/Ctrl + ,)
Click ‘Open Settings (JSON)’ in the top right corner
Add the MCP configuration provided by the wizard to your settings
Save the file and reload VS Code (Cmd/Ctrl + Shift + P → “Reload Window”)

The configuration will look like this (the wizard pre-fills your token):

{
  "mcp.servers": {
    "corestory": {
      "url": "https://c2s.corestory.ai/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}

Config file location: ~/.vscode/settings.json or .vscode/settings.json in your workspace.

Step 5: Verify Setup

The final screen confirms your setup is complete and offers an optional token validation check to verify your token exists and hasn’t been revoked. To fully test the connection, open your configured IDE, start a new AI chat or conversation, and try asking about your codebase.

Managing Tokens from the Dashboard

The IDE Integrations section in Settings also shows all your existing MCP tokens in a table with their name, creation date, and last used date. From here you can:

Create new tokens — click “Create New Token” to generate additional tokens (e.g., one per device or IDE)
Delete tokens — click the delete button next to any token to revoke it immediately

Best practice: Use a separate token for each tool or device so you can revoke access individually if needed.

Setup via API

For organizations with direct API access, token creation and MCP configuration can also be done via the API documentation interface.

Step 1: Get Your MCP Token

MCP tokens are separate from your regular CoreStory login and provide scoped access to your organization’s data.

Create a Token

Visit the CoreStory API Documentation:
- Go to: https://c2s.corestory.ai/docs (or your deployment’s /docs endpoint)
- Log in with your CoreStory credentials if prompted
Navigate to MCP Token Management:
- Scroll to the “MCP Token Management” section
- Find the POST /api/mcp-tokens endpoint
Create your token:
- Click “Execute” or expand the endpoint
- Fill in the request body:

{
  "name": "Claude Desktop - MacBook Pro",
  "description": "Personal development machine",
  "expires_days": 30
}

Click “Execute” button

Copy the token immediately:
- The response will contain your token starting with mcp_:

mcp_abc123.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Important: This token is shown ONLY ONCE. Copy it now!

Store it securely:
- Save in your password manager
- Or store in environment variables
- Never commit to Git or share publicly

Token Format

mcp_{token_id}.{jwt_token}

Important: Tokens are organization-scoped and provide access to all projects in your workspace.

Step 2: Configure MCP Server Connection

The CoreStory MCP server URL structure:

https://c2s.corestory.ai/mcp

Step 3: Setup in Your AI Tool

Claude Code

Claude Code is a command-line tool that lets you delegate coding tasks to Claude directly from your terminal.

Add CoreStory MCP server — In your terminal, run the following command:

claude mcp add --transport http corestory https://c2s.corestory.ai/mcp \
  --header "Authorization: Bearer your-token"

Start Claude Code — Enter the claude command to start a Claude Code session
Verify connection: Run a test command:

"List my CoreStory projects"

Note: Claude Code automatically has access to your local filesystem and can create/modify files based on CoreStory context.

Cursor

Open Cursor Settings (Cmd/Ctrl + ,)
Navigate to: Tools & MCP
Add new MCP server:

{
  "mcpServers": {
    "corestory": {
      "url": "https://c2s.corestory.ai/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}

Save and restart Cursor
Verify: Open a new chat and check that CoreStory tools are available

GitHub Copilot / VS Code

Install the MCP extension (if available) or use VS Code’s built-in MCP support
Open VS Code Settings (Cmd/Ctrl + ,)
Search for: “MCP” or “Model Context Protocol”
Add server configuration:

{
  "mcpServers": {
    "corestory": {
      "url": "https://c2s.corestory.ai/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN_HERE"
      }
    }
  }
}

Reload VS Code window (Cmd/Ctrl + Shift + P → “Reload Window”)
Verify: Use Copilot Chat and check for CoreStory context availability

Devin

Devin uses an MCP Marketplace with both pre-configured integrations and custom server support.

Navigate to: Settings > MCP Marketplace
Click “Add Your Own”
Configure the MCP server:
- Transport Type: Select HTTP
- Server URL: https://c2s.corestory.ai/mcp
Add a New Secret:
1. Name your secret $API_TOKEN
2. In the “Secret Value” field, enter mcp_YOUR_TOKEN_HERE
3. Save secret
Authentication: Add authorization header
- Key: Authorization
- Value: Bearer $API_TOKEN
Enable integration
Click “Test listing tools” to verify connection
Save configuration

Verify: Start a Devin session and ask: “Can you list my CoreStory projects?” Note: Devin supports three transport methods: stdio, SSE, and HTTP. Use HTTP for CoreStory’s remote server.

Factory.ai

Factory’s droid CLI connects to remote MCP servers via HTTP. Add CoreStory MCP server:

Type /mcp within droid to open the MCP management UI
Choose + Add MCP server manually
- Server Name: CoreStory
- Server Type: http (remote)
- URL: https://c2s.corestory.ai/mcp
- Add header: Authorization: Bearer mcp_YOUR_TOKEN_HERE
Test by asking droid: “List my CoreStory projects”

Configuration stored at: ~/.factory/mcp.json

You may need to open the .factory/mcp.json file and save it or restart Droid before the CoreStory MCP will show a “Connected” status.

Troubleshooting:

Ensure droid CLI is installed and updated
Check header syntax if authentication fails
Use /mcp UI to view server status and error messages

Available Tools

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

Tool	Description
`list_projects`	List all projects in your organization
`get_project_prd`	Retrieve Product Requirements Document
`get_project_techspec`	Retrieve Technical Specification
`list_conversations`	List project conversations
`get_conversation`	Get conversation details and history
`create_conversation`	Create new conversation
`rename_conversation`	Rename existing conversation
`send_message`	Send message to conversation (streaming response)

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

Testing Your Connection

Quick Test

Ask your AI assistant:

Can you list my CoreStory projects?

The assistant should call the list_projects tool and show your projects.

Manual Test (curl)

# Set your token
export MCP_TOKEN="mcp_YOUR_TOKEN_HERE"

# Test connection
curl -X POST https://c2s.corestory.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

Expected response: JSON list of available tools

Troubleshooting

Connection Issues

Problem: “Cannot connect to MCP server” Solutions:

Verify the server URL is correct: https://c2s.corestory.ai/mcp
Check your internet connection
Confirm MCP server is running (check CoreStory status page)

Authentication Errors

Problem: “Authentication failed” or “Invalid token” Solutions:

Verify token format starts with mcp_
Check token hasn’t expired
Ensure Bearer prefix is included in header: Bearer mcp_...
Create a new token if current one is invalid
Verify token is for the correct organization

Tool Not Available

Problem: AI assistant says “CoreStory tools not available” Solutions:

Restart your AI tool completely
Verify MCP server appears in tool’s connected servers list
Check configuration file syntax (JSON must be valid)
Look for error messages in tool’s developer console/logs

Tools List Empty

Problem: Connection succeeds but no tools appear Solutions:

Test with tools/list method manually (see Testing section)
Check if your organization has active projects
Verify token has correct permissions
Review MCP server logs for errors

Slow or Timeout Responses

Problem: Tool calls take too long or timeout Solutions:

Check your network connection speed
Try with a smaller project first
For large PRDs/TechSpecs, request specific sections
Increase timeout settings in your AI tool if possible

Managing Tokens

View Your Tokens

Visit https://c2s.corestory.ai/docs
Navigate to GET /api/mcp-tokens
Click “Execute” to see all your tokens

View Token Details

Navigate to GET /api/mcp-tokens/{token_id}
Enter the token ID
Click “Execute” to see details (name, description, created date, last used, etc.)

Revoke a Token

Navigate to DELETE /api/mcp-tokens/{token_id}
Enter the token ID you want to revoke
Click “Execute” to permanently revoke the token

Alternative (API): You can also manage tokens programmatically:

# List tokens
curl https://c2s.corestory.ai/mcp/mcp-tokens \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

# Revoke token
curl -X DELETE https://c2s.corestory.ai/mcp/mcp-tokens/{token_id} \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Best Practice: Rotate tokens every 90-365 days, and immediately revoke any compromised tokens.

Security Best Practices

Never commit tokens to Git — Use environment variables or secure config files
Use separate tokens per tool — Easier to track and revoke if needed
Set reasonable expiration dates — 90-365 days recommended
Revoke unused tokens — Clean up tokens you’re no longer using
Monitor token usage — Review which tokens are accessing your projects

Support

Getting Help

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

Useful Debug Commands

# Check server health
curl https://c2s.corestory.ai/mcp/health

# Get server info
curl https://c2s.corestory.ai/mcp

# List available tools
curl -X POST https://c2s.corestory.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Updates & Changelog

This integration follows the MCP specification. Check CoreStory release notes for:

New tool additions
API changes
Deprecation notices
Security updates

Last Updated: February 2026

About CoreStory

Getting Started

Product

Documentation Index

​What is the CoreStory MCP Server?

​Prerequisites

​Quick Setup (Dashboard)

​Step 1: Open IDE Integrations

​Step 2: Generate an MCP Token

​Step 3: Select Your IDE

​Step 4: Configure Your IDE

​Step 5: Verify Setup

​Managing Tokens from the Dashboard

​Setup via API

​Step 1: Get Your MCP Token

​Create a Token

​Token Format

​Step 2: Configure MCP Server Connection

​Step 3: Setup in Your AI Tool

​Claude Code

​Cursor

​GitHub Copilot / VS Code

​Devin

​Factory.ai

​Available Tools

​Testing Your Connection

​Quick Test

​Manual Test (curl)

​Troubleshooting

​Connection Issues

​Authentication Errors

​Tool Not Available

​Tools List Empty

​Slow or Timeout Responses

​Managing Tokens

​View Your Tokens

​View Token Details

​Revoke a Token

​Security Best Practices

​Support

​Getting Help

​Useful Debug Commands

​Updates & Changelog

What is the CoreStory MCP Server?

Prerequisites

Quick Setup (Dashboard)

Step 1: Open IDE Integrations

Step 2: Generate an MCP Token

Step 3: Select Your IDE

Step 4: Configure Your IDE

Step 5: Verify Setup

Managing Tokens from the Dashboard

Setup via API

Step 1: Get Your MCP Token

Create a Token

Token Format

Step 2: Configure MCP Server Connection

Step 3: Setup in Your AI Tool

Claude Code

Cursor

GitHub Copilot / VS Code

Devin

Factory.ai

Available Tools

Testing Your Connection

Quick Test

Manual Test (curl)

Troubleshooting

Connection Issues

Authentication Errors

Tool Not Available

Tools List Empty

Slow or Timeout Responses

Managing Tokens

View Your Tokens

View Token Details

Revoke a Token

Security Best Practices

Support

Getting Help

Useful Debug Commands

Updates & Changelog