> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corestory.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Supercharging AI Agents with CoreStory
> How CoreStory's persistent code intelligence makes AI coding agents dramatically more effective across your development workflow.
## Overview
AI coding agents are only as good as the context they have. Without architectural understanding, they guess — reinventing existing services, violating naming conventions, breaking invariants they didn't know existed. The result is code that works in isolation but doesn't fit the system.
CoreStory eliminates this problem by giving your AI agent access to **code intelligence** — synthesized knowledge about how your system actually works, drawn from PRDs, technical specifications, user stories, code history, and architecture analysis. The agent queries this intelligence through MCP (Model Context Protocol) to understand the system *before* writing code, not after.
This guide shows you how to connect CoreStory to your AI coding agent, verify the connection, and start using code intelligence in your development workflows. For specific workflow playbooks (bug resolution, feature implementation, spec-driven development), see the links in the Use Cases section.
### What CoreStory Gives Your Agent
CoreStory serves two roles in every workflow:
* **Expert** — answers questions about intended system behavior, invariants, business rules, architectural patterns, and design history. This is context synthesized from your entire codebase — not just file contents, but the *meaning* behind them.
* **Navigator** — points to specific files, methods, extension points, and code paths relevant to a task. Instead of grep-wandering through a codebase, the agent gets directed guidance.
Together, these roles let the agent operate like a senior engineer who's been on the team for years — understanding not just what the code does, but *why* it does it that way.
***
## Prerequisites
* A **CoreStory account** with at least one project that has completed ingestion
* An **AI coding agent** that supports MCP (see Supported Agents below)
* A **code repository** the agent can read and write to
***
## Quick Start
### Step 1: Copy Your MCP URL
1. Go to **Settings** in the [CoreStory Dashboard](https://app.corestory.ai/settings)
2. Under **Organization Related**, open **IDE Integrations**
3. Click **Copy** next to **Your MCP URL**
The URL is scoped to one organization and looks like this:
```
https://app.corestory.ai/mcp/{your-org-slug}-{org-id}
```
### Step 2: Configure Your Agent
Add that URL to your agent as an HTTP (streamable) remote MCP server, with **no authorization header**. The first time the agent connects, it opens your browser to sign in to CoreStory — there is no token to copy or store.
For per-client instructions, see the [MCP Server Setup guide](/getting-started/mcp-server-setup). The Supported Agents section below covers what is specific to *agentic* workflows.
### Step 3: Verify the Connection
Ask your agent:
```
List my CoreStory projects.
```
If it returns your projects, the MCP connection is working. If not, check the Troubleshooting section.
### Step 4: Verify Project Readiness
Before starting any task, confirm your project has completed ingestion:
```
List my CoreStory projects. Which ones are ready to use?
```
Your agent will call `list_projects` and return project details including status. Confirm the project you want to work with is ready before proceeding.
***
## CoreStory MCP 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 |
### The Core Interaction Pattern
Most CoreStory workflows follow this pattern:
1. **Select project** — `list_projects` → confirm the right project
2. **Create conversation** — `create_conversation` with a descriptive title
3. **Query the Expert** — `send_message` to understand system behavior, invariants, and architecture
4. **Query the Navigator** — `send_message` to find specific files, methods, and extension points
5. **Act on the knowledge** — implement, test, or document based on what CoreStory revealed
6. **Close the loop** — `rename_conversation` to mark the thread as resolved
The conversation persists as institutional knowledge — future queries in the same thread benefit from accumulated context.
***
## Use Cases
CoreStory's code intelligence powers a range of development workflows. Each has a dedicated playbook with step-by-step implementation guidance:
| Use Case | Description | Playbook |
| - | - | - |
| **Bug Resolution** | Diagnose and fix bugs with full architectural context. The agent queries CoreStory to understand how the system *should* work, generates root cause hypotheses, writes a failing test, and implements a minimal fix. | [Agentic Bug Resolution](/playbooks/agentic-bug-resolution) |
| **Feature Implementation** | Implement features from tickets using CoreStory to understand existing patterns, data structures, and integration points. TDD workflow with continuous architectural validation. | [Feature Implementation](/playbooks/feature-implementation) |
| **Spec-Driven Development** | Write architecture-grounded specifications before implementation. CoreStory provides the architectural truth that standalone SDD tools can't — ensuring specs describe delta changes constrained by what actually exists. | [Spec-Driven Development](/playbooks/spec-driven-development) |
| **Test Generation** | Derive comprehensive test suites from CoreStory specifications — behavioral tests, E2E journey tests, edge cases, error contracts, and authorization matrices. | [Spec-Driven Test Generation](/playbooks/spec-driven-test-generation) |
| **M\&A Technical Due Diligence** | Analyze acquisition targets using CoreStory to understand architecture, identify risks, assess technical debt, and evaluate integration complexity. | [M\&A Due Diligence](/playbooks/ma-technical-due-diligence) |
### Additional Use Cases
These workflows don't have dedicated playbooks but follow the same Expert → Navigator pattern:
* **Spec/Code Gap Analysis** — identify discrepancies between CoreStory specifications and actual implementation, then remediate
* **Architecture Comprehension** — understand component boundaries, data flows, and integration points for refactoring or onboarding
* **API Contract Validation** — extract API contracts from specs, validate against code, and generate contract tests
* **Security Baseline Review** — audit error handling, validation, and idempotency against spec security sections
* **Developer Onboarding Documentation** — generate onboarding guides by cross-referencing CoreStory specs with source code
* **Release Notes Generation** — analyze feature changes and generate release notes keyed to business rules and endpoints
***
## Supported Agents & Configuration
CoreStory works with any MCP-capable AI coding agent. The connection itself is the same everywhere — point the agent at your MCP URL with no authorization header and complete the browser sign-in.
Per-client connection steps live in the [MCP Server Setup guide](/getting-started/mcp-server-setup) so there is one place to keep current. This section covers the part that differs per agent: **where each one expects workflow files to live.**
Each workflow playbook ships a ready-to-use SKILL.md. Install it where your harness looks for it:
The skill file shown below is plain markdown. The workflow it encodes works in any agentic harness — only the install location differs. Common conventions:
| Harness | Install location |
| - | - |
| **Claude Code** | `.claude/skills//SKILL.md` — Claude loads the body when the YAML `description` matches the task |
| **GitHub Copilot** | Append to `.github/copilot-instructions.md` for repo-wide instructions, or save as `.github/instructions/.instructions.md` with an `applyTo` glob for path-scoped use |
| **Cursor** | `.cursor/rules/.mdc` with a `description` field for auto-attach (use `globs` for path-scoped or `alwaysApply: true` for every session) |
| **Factory.ai** | `.factory/droids/.md` (project) or `~/.factory/droids/.md` (personal); Factory loads it as a custom Droid |
| **Aider** | `CONVENTIONS.md` at repo root, loaded with `aider --read CONVENTIONS.md` — or add it to the `read:` list in `.aider.conf.yml` for automatic loading |
| **Codex / `AGENTS.md` harnesses** | Append the content to `AGENTS.md` at your repository root |
| **Custom runtime** | Load the markdown into your agent's system prompt, rules file, or wherever it consumes workflow context |
Want a single install that works across the most harnesses? Append the content to `AGENTS.md` at your repository root. The [`AGENTS.md` spec](https://agents.md/) is read by Codex, Aider, Cursor, Factory, Jules, Gemini CLI, Windsurf, GitHub Copilot's coding agent, JetBrains Junie, Warp, and others — so a single file covers most users without harness-specific setup.
If your harness isn't listed, the SKILL.md content itself is portable — install it wherever your harness loads workflow context and adapt the activation step (auto-trigger, slash command, explicit invocation) to your harness's conventions.
### Verifying the Connection
| Agent | How to verify |
| - | - |
| **Claude Code** | Run `/mcp` to confirm `corestory` is connected and authenticated |
| **GitHub Copilot (VS Code)** | Open Copilot Chat → **Agent** mode → tools icon → confirm CoreStory tools appear |
| **Cursor** | Open the AI pane → **Agent** mode → confirm CoreStory tools appear in the tools list |
| **Factory.ai / Devin / Windsurf** | Ask the agent: "List my CoreStory projects" |
Most clients list a server's tools *before* sign-in completes, because `tools/list` does not require authentication. Seeing CoreStory tools is not proof you are authenticated — calling one is. If tools appear but every call fails with an authorization error, finish the browser sign-in.
***
## Best Practices
### Effective CoreStory Queries
The quality of CoreStory's responses depends on the specificity of your queries.
**Be specific, not broad:**
| Instead of | Try |
| - | - |
| "Tell me about the order system" | "What is the validation logic for order placement? What fields are required, what are the business rules for minimum amounts, and how is stock validation handled?" |
| "How does authentication work?" | "What is the session timeout configuration? How are JWT tokens validated, and what happens when a token expires during an active request?" |
| "Tell me about the API" | "What are the error response formats for the payment endpoints? Do they follow RFC-7807? What HTTP status codes map to which error conditions?" |
**Use specific variable names and code references** when you have them — CoreStory can resolve references to actual files and methods in the codebase.
### Expert Before Navigator
Always query for *understanding* before querying for *location*. The Expert phase (how does this work? what are the invariants?) should come before the Navigator phase (which files do I need to change?). This prevents the agent from diving into code changes before understanding the system's constraints.
### Conversation Hygiene
* **One conversation per task.** Create a conversation with a descriptive title like "Bug Fix: #1234 — Payment retry failing on 503 errors" or "Feature: #412 — Webhook notification system."
* **Reuse conversations** for follow-up queries on the same task. The conversation accumulates context that improves subsequent responses.
* **Rename when done.** Mark completed conversations with a prefix like "✅ Resolved:" so future users can find institutional knowledge.
### Cost Control
* **Retrieve before regenerating.** Use `get_project_prd` and `get_project_techspec` to check if documents already exist before asking the agent to generate new content.
* **Reuse conversations** instead of creating new ones for related queries — conversation context reduces the need for repeated background queries.
* **Batch queries.** Plan your questions in advance and ask comprehensive questions instead of many small ones.
### Security
* **Prefer the browser sign-in over tokens.** OAuth stores a short-lived credential in your agent's own credential store, so nothing sensitive lands in the config files you commit.
* **Share the MCP URL, not credentials.** A project-scoped config file can safely contain the URL — each teammate signs in as themselves and sees only what their CoreStory account allows.
* **Revoke leftover legacy tokens** in **Settings → IDE Integrations → Legacy tokens** once you have migrated.
* **Review generated content** for sensitive data before committing to public repositories.
***
## Troubleshooting
### Agent Can't See CoreStory Tools
**Symptoms:** Agent doesn't list CoreStory tools, can't access CoreStory resources, or errors about missing MCP server.
**Solutions:**
1. Verify the MCP server appears in your agent's server list (e.g., `claude mcp list` for Claude Code, or the tools panel in VS Code/Cursor)
2. Confirm you completed the browser sign-in — in Claude Code, run `/mcp`, select `corestory`, and choose **Authenticate**
3. Verify the URL matches the one in **Settings → IDE Integrations** exactly, including the org slug
4. Check that no stale `Authorization` header is left over from the deprecated token flow — it suppresses the browser sign-in
5. Restart your agent after configuration changes
6. Ask the agent to list available MCP servers and tools as a diagnostic
### Project Not Found or Ingestion Incomplete
**Symptoms:** `list_projects` returns empty, or queries return incomplete/stale data.
**Solutions:**
1. Verify you have access to the project in the CoreStory dashboard
2. Check ingestion status — projects must show "completed" or "ready" before querying
3. If ingestion appears stuck, contact CoreStory support
4. Don't proceed with heavy queries until ingestion is complete
### Slow or Rate-Limited Responses
**Symptoms:** Slow responses, timeouts, or rate-limiting errors.
**Solutions:**
1. Reduce query frequency — batch related questions into single, comprehensive queries
2. Reuse conversations instead of creating new ones
3. Retrieve existing documents instead of regenerating
4. Use incremental section generation instead of full document generation
### Agent Times Out on Long Tasks
**Symptoms:** Agent sessions end before completing multi-step workflows.
**Solutions:**
1. Break large tasks into milestones — have the agent commit after each phase
2. Use the conversation ID to resume context in a new session
3. For agents with session limits (e.g., Devin ACU limits), prioritize the Expert and Navigator phases first, then implement in a separate session
***
## What's Next
Once you've verified your CoreStory connection, pick a workflow and follow its playbook:
* **First time?** Start with [Bug Resolution](/playbooks/agentic-bug-resolution) — it's the most concrete workflow and demonstrates the Expert → Navigator → Implement pattern clearly.
* **Building something new?** Use [Spec-Driven Development](/playbooks/spec-driven-development) to ground your specification in the real architecture before implementation.
* **Working from tickets?** [Feature Implementation](/playbooks/feature-implementation) covers the full ticket-to-merge workflow with TDD and continuous architectural validation.
Each playbook includes agent-specific configuration files (skills, instructions, rules, droids) that encode the workflow so your agent follows it automatically.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.