
Cortex builds a local knowledge graph of your codebase using tree-sitter parsing, then exposes it to Claude and other MCP clients through semantic search and relationship queries. It indexes files, symbols, architectural decision records, and the connections between them (calls, imports, deprecations), so your assistant retrieves the right context instead of dumping entire directories into the prompt. The setup is one command: `cortex init --bootstrap` scaffolds the index, installs git hooks to keep it fresh, and registers the MCP server with Claude Desktop or Codex. You get graph traversal queries, call graph lookups, and rule enforcement at retrieval time. Runs entirely local with WSL support for Windows users running Node in a Linux environment.
Public tool metadata for what this MCP can expose to an agent.
listAllEntitiesList and filter catalog entities with support for pagination, search, and various filters including groups, types, owners, and git repositories. If the client is trying to fetch data for teams, use 'type': 'team' in these APIs.16 paramsList and filter catalog entities with support for pagination, search, and various filters including groups, types, owners, and git repositories. If the client is trying to fetch data for teams, use 'type': 'team' in these APIs.
contextstringgitRepositoriesarraygroupsarrayhierarchyDepthstringincludeArchivedbooleanincludeHierarchyFieldsarrayincludeLinksbooleanincludeMetadatabooleanincludeNestedFieldsarrayincludeOwnersbooleanincludeSlackChannelsbooleanownersarraypageintegerpageSizeintegerquerystringtypesarraylistEntityDescriptorsCortex Catalog API - Access and manage your service catalog, teams, domains, and resources5 paramsCortex Catalog API - Access and manage your service catalog, teams, domains, and resources
contextstringpageintegerpageSizeintegertypesarrayyamlbooleanlistDependenciesForEntityList all dependencies for an entity including both incoming (who depends on this service) and outgoing (what this service depends on) relationships. Essential for understanding service interactions, planning changes, and assessing blast radius6 paramsList all dependencies for an entity including both incoming (who depends on this service) and outgoing (what this service depends on) relationships. Essential for understanding service interactions, planning changes, and assessing blast radius
callerTagstringcontextstringincludeIncomingbooleanincludeOutgoingbooleanpageintegerpageSizeintegergetDependencyGet specific dependency details between two entities including method, path, and metadata. Useful for understanding the nature of the relationship, API contracts, and communication patterns between services5 paramsGet specific dependency details between two entities including method, path, and metadata. Useful for understanding the nature of the relationship, API contracts, and communication patterns between services
calleeTagstringcallerTagstringcontextstringmethodstringpathstringgetEntityDetailsRetrieve comprehensive details about a specific entity including its metadata, ownership, hierarchies, and relationships. This is the primary method for getting complete information about services, teams, or domains.5 paramsRetrieve comprehensive details about a specific entity including its metadata, ownership, hierarchies, and relationships. This is the primary method for getting complete information about services, teams, or domains.
contextstringhierarchyDepthstringincludeHierarchyFieldsarrayincludeOwnersbooleantagOrIdstringgetCustomDataForEntityList all custom data key-value pairs associated with an entity. Retrieve metadata, configuration settings, and custom attributes stored for services, resources, or domains. Supports pagination for entities with large amounts of custom data4 paramsList all custom data key-value pairs associated with an entity. Retrieve metadata, configuration settings, and custom attributes stored for services, resources, or domains. Supports pagination for entities with large amounts of custom data
contextstringpageintegerpageSizeintegertagOrIdstringgetCustomDataForEntityByKeyRetrieve a specific custom data value by key for an entity. Efficiently access individual metadata attributes, configuration values, or custom properties without fetching all custom data3 paramsRetrieve a specific custom data value by key for an entity. Efficiently access individual metadata attributes, configuration values, or custom properties without fetching all custom data
contextstringkeystringtagOrIdstringlistCustomEventsForEntityList custom events for an entity with optional filtering by type and time range. Supports pagination and filtering by event type, start time, and end time to retrieve historical event data8 paramsList custom events for an entity with optional filtering by type and time range. Supports pagination and filtering by event type, start time, and end time to retrieve historical event data
contextstringendTimestringpageintegerpageSizeintegerstartTimestringtagOrIdstringtimestampstringtypestringgetCustomEventForEntityByUuidRetrieve a specific custom event by its UUID. Returns event details including title, description, timestamp, type, and any custom data associated with the event3 paramsRetrieve a specific custom event by its UUID. Returns event details including title, description, timestamp, type, and any custom data associated with the event
contextstringtagOrIdstringuuidstringgetDeploysForEntityList all deployments for a specific catalog entity. Returns deployment history including timestamps, environments, SHAs, and deployment types in paginated format4 paramsList all deployments for a specific catalog entity. Returns deployment history including timestamps, environments, SHAs, and deployment types in paginated format
contextstringpageintegerpageSizeintegertagOrIdstringgetCurrentOncallForEntityRetrieve the current on-call personnel for an entity in real-time. Shows who is actively responsible for incident response, including primary and secondary on-call, contact information, and rotation schedules2 paramsRetrieve the current on-call personnel for an entity in real-time. Shows who is actively responsible for incident response, including primary and secondary on-call, contact information, and rotation schedules
contextstringtagOrIdstringgetEntityDescriptorCortex Catalog API - Access and manage your service catalog, teams, domains, and resources3 paramsCortex Catalog API - Access and manage your service catalog, teams, domains, and resources
contextstringtagOrIdstringyamlbooleanlistEntityDestinationsForRelationshipTypeList all destinations for a certain relationship type & entity. Use the listRelationshipTypes tool to find the relevant relationshipTypeTag.5 paramsList all destinations for a certain relationship type & entity. Use the listRelationshipTypes tool to find the relevant relationshipTypeTag.
contextstringdepthstringincludeArchivedbooleanrelationshipTypeTagstringtagOrIdstringlistEntitySourcesForRelationshipTypeList all sources for a certain relationship type & entity. Use the listRelationshipTypes tool to find the relevant relationshipTypeTag.5 paramsList all sources for a certain relationship type & entity. Use the listRelationshipTypes tool to find the relevant relationshipTypeTag.
contextstringdepthstringincludeArchivedbooleanrelationshipTypeTagstringtagOrIdstringgetCustomMetricDataRetrieve custom metric data points for an entity. Returns paginated time-series data for a specific custom metric, with optional filtering by date range to analyze trends and patterns7 paramsRetrieve custom metric data points for an entity. Returns paginated time-series data for a specific custom metric, with optional filtering by date range to analyze trends and patterns
contextstringcustomMetricKeystringendDatestringpageintegerpageSizeintegerstartDatestringtagOrIdstringqueryPointInTimeMetricsExecute point-in-time queries for one or more engineering metrics. Returns current metric values for specified time periods, with support for batch queries and optional period-over-period comparisons. Time range (startTime/endTime) cannot exceed 6 months (180 days). PREREQUISI...14 paramsExecute point-in-time queries for one or more engineering metrics. Returns current metric values for specified time periods, with support for batch queries and optional period-over-period comparisons. Time range (startTime/endTime) cannot exceed 6 months (180 days). PREREQUISI...
comparisonvaluecontextstringendTimestringfiltersarraygroupByarraylimitintegermetricsarraynestedGroupByarraynestedMetricsarraynestedTimeAttributestringnextPagestringorderByarraystartTimestringtimeAttributestringlistMetricDefinitionsList all available engineering metric definitions. USAGE - Call this endpoint BEFORE querying metrics (queryPointInTimeMetrics): 1. Once at start: Call with view='basic' to discover all available metrics - cache this response 2. Once per metric: Call with view='full' and key=M...3 paramsList all available engineering metric definitions. USAGE - Call this endpoint BEFORE querying metrics (queryPointInTimeMetrics): 1. Once at start: Call with view='basic' to discover all available metrics - cache this response 2. Once per metric: Call with view='full' and key=M...
contextstringkeyarrayviewstringlistInitiativesList all initiatives in the organization with optional filters for draft and expired initiatives. View active improvement programs, strategic projects, and their current status to understand organizational priorities and track progress5 paramsList all initiatives in the organization with optional filters for draft and expired initiatives. View active improvement programs, strategic projects, and their current status to understand organizational priorities and track progress
contextstringincludeDraftsbooleanincludeExpiredbooleanpageintegerpageSizeintegergetInitiativeRetrieve detailed information about a specific initiative including its goals, timeline, affected entities, scorecard targets, and current progress. Essential for understanding initiative scope and tracking achievement of objectives2 paramsRetrieve detailed information about a specific initiative including its goals, timeline, affected entities, scorecard targets, and current progress. Essential for understanding initiative scope and tracking achievement of objectives
cidstringcontextstringgetMyWorkspaceTOOL for retrieving current user's owned resources and work items across the Cortex workspace. FLEXIBLE REQUEST STRUCTURE: The request accepts an object with optional fields for each resource type: - myEntitiesRequest: Fetch entities (services, resources, domains) owned by the...7 paramsTOOL for retrieving current user's owned resources and work items across the Cortex workspace. FLEXIBLE REQUEST STRUCTURE: The request accepts an object with optional fields for each resource type: - myEntitiesRequest: Fetch entities (services, resources, domains) owned by the...
contextstringmyEntitiesRequestobjectmyOpenPRsRequestobjectmyRequestedReviewsRequestobjectmyScorecardsRequestobjectmyTeamsRequestobjectmyWorkItemsRequestobjectlistRelationshipTypesList all available relationship types with pagination. View relationship type configurations to understand what kinds of relationships can be created between entities like services, resources, domains, and teams3 paramsList all available relationship types with pagination. View relationship type configurations to understand what kinds of relationships can be created between entities like services, resources, domains, and teams
contextstringpageintegerpageSizeintegergetRelationshipTypeDetailsGet complete details of a specific relationship type including its configuration, rules, source/destination filters, and inheritance settings. Essential for understanding how entities can be connected and what validation rules apply2 paramsGet complete details of a specific relationship type including its configuration, rules, source/destination filters, and inheritance settings. Essential for understanding how entities can be connected and what validation rules apply
contextstringrelationshipTypeTagstringlistEntityRelationshipsList all entity relationships/full graph for a specific relationship type across the entire organization. Returns paginated results showing all source-destination pairs, useful for understanding the complete relationship graph and finding all connections of a particular type4 paramsList all entity relationships/full graph for a specific relationship type across the entire organization. Returns paginated results showing all source-destination pairs, useful for understanding the complete relationship graph and finding all connections of a particular type
contextstringpageintegerpageSizeintegerrelationshipTypeTagstringlistScorecardsList all scorecards in the organization with optional filtering. View scorecard configurations to understand quality standards, compliance requirements, and maturity models. Supports filtering by groups, entities, and teams to find relevant scorecards7 paramsList all scorecards in the organization with optional filtering. View scorecard configurations to understand quality standards, compliance requirements, and maturity models. Supports filtering by groups, entities, and teams to find relevant scorecards
contextstringentitiesarraygroupsarraypageintegerpageSizeintegershowDraftsbooleanteamsarraygetScorecardGet complete details of a scorecard including its configuration, rules, levels, weights, exemption settings, and evaluation criteria. Essential for understanding how services are evaluated and what standards they must meet2 paramsGet complete details of a scorecard including its configuration, rules, levels, weights, exemption settings, and evaluation criteria. Essential for understanding how services are evaluated and what standards they must meet
contextstringtagstringgetScorecardNextStepsForEntityGet actionable next steps for an entity to improve its scorecard performance. Shows which rules need to be satisfied to reach the next maturity level, helping teams prioritize improvements and track progress toward compliance goals3 paramsGet actionable next steps for an entity to improve its scorecard performance. Shows which rules need to be satisfied to reach the next maturity level, helping teams prioritize improvements and track progress toward compliance goals
contextstringentityTagstringtagstringlistScorecardScoresRetrieve scores for all entities evaluated by a specific scorecard. Returns paginated results showing how each service, resource, or domain performs against the scorecard's rules, including individual rule scores and overall scorecard scores5 paramsRetrieve scores for all entities evaluated by a specific scorecard. Returns paginated results showing how each service, resource, or domain performs against the scorecard's rules, including individual rule scores and overall scorecard scores
contextstringentityTagstringpageintegerpageSizeintegertagstringgetTeamDetailsRetrieve detailed information about a specific team by its tag or ID. Returns complete team data including members, slack channels, metadata, and whether it's backed by an identity provider group2 paramsRetrieve detailed information about a specific team by its tag or ID. Returns complete team data including members, slack channels, metadata, and whether it's backed by an identity provider group
contextstringtagOrIdstringquery_docsQuery the Cortex knowledge base for answers. Args: query: The question to ask Cortex docs Returns: Response from Cortex including answer and metadata2 paramsQuery the Cortex knowledge base for answers. Args: query: The question to ask Cortex docs Returns: Response from Cortex including answer and metadata
contextstringquerystringget_more_toolsCheck for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.1 paramsCheck for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.
contextvalue
Give AI coding agents the right context from your repository.
Cortex builds a local map of your code, symbols, relationships, and project rules. Coding agents query that map through the CLI instead of guessing or reading the whole repository.
Your code stays on your machine. MCP is not required.
Requires Node.js 20.9+ and Git.
npm install --global @danielblomma/cortex-mcp
cd your-project
cortex init --bootstrap
This indexes the repository, adds Cortex instructions to AGENTS.md, installs
Git hooks, and starts the background watcher.
Check the setup:
cortex doctor
# Find relevant code.
cortex search "where is authentication handled?" --json
# Follow relationships from a search result.
cortex related <entity-id> --json
# See what a change may affect.
cortex impact "authentication" --json
# Read repository rules.
cortex rules --json
# Compare a changed file with nearby patterns.
cortex pattern-evidence src/auth.ts --json
# Inspect deterministic active conventions for a file or indexed entity.
cortex conventions src/payments/retry.ts --json
# Get cited, deterministic context before implementing a code task.
cortex guidance src/payments/retry.ts --task "add bounded retry handling" --json
# Review the staged, unstaged, and non-ignored untracked candidate against HEAD.
cortex review --diff --json
# Refresh context after significant changes.
cortex update
Agents can run these commands directly. cortex init adds instructions that
tell them to search before answering and check impact before refactoring. They
do not need an MCP connection.
Without Cortex, an agent often searches by filename and reads many unrelated files. Cortex gives it structured repository context:
The pipeline is local and straightforward:
repository -> local index -> Cortex CLI -> coding agent
| Command | Purpose |
|---|---|
cortex search "..." --json | Find relevant code and context |
cortex related <entity-id> --json | Follow relationships from a result |
cortex impact "..." --json | Estimate the blast radius of a change |
cortex rules --json | Show active repository rules |
cortex pattern-evidence <file> --json | Find nearby implementation patterns |
cortex conventions <file-or-entity> --json | Inspect bounded repository convention profiles |
cortex guidance <file-or-entity> --task <text> --json | Get bounded cited pre-coding guidance |
cortex review --diff --json | Review the current Git candidate with cited local evidence |
cortex update | Refresh changed context |
cortex status | Show index status |
cortex doctor | Diagnose the local setup |
cortex watch status | Check background synchronization |
cortex dashboard | Open the local status dashboard |
Run cortex help for the complete command list.
cortex conventions uses only the local index. It returns bounded, live-backed
version-1 profiles and does not call a model, planner, provider, or network
service. See Repository convention profiles
for the exact eligibility, limit, hashing, persistence, and safety contract.
Before implementing a code task, use cortex guidance as cited additive
context—not policy authority. Continue to use normal search, related, and
impact when needed, and never skip explicit active rules or conflicts. The
command is local-only and inspection-only; see the exact versioned contract in
Pre-coding guidance.
After coding and before finalization, use cortex review --diff. It separates
exact source-of-truth violations from heuristic local-pattern warnings and is
inspection-only. See Deterministic diff review.
Git hooks and the watcher normally update Cortex automatically.
cortex status
cortex watch status
cortex update
Run cortex update manually after a large change or when results look stale.
Make lexical and graph search available first while semantic indexing continues in the background:
cortex bootstrap --background --profile interactive
cortex indexing status --json
This mode supports macOS, Linux, and WSL. Native Windows should use normal foreground bootstrap.
npm install --global @danielblomma/cortex-mcp@latest
cortex init --force
cortex bootstrap
cortex update
Project configuration and rules are preserved. See CHANGELOG.md for version-specific notes.
The normal Cortex workflow uses the CLI. If a client explicitly requires MCP,
run cortex connect.
Cortex supports DeepSeek Harness through the V1 explicit tools and skills
integration. Cortex 2.6.0 contains and validates the integration source against
the pinned Harness 0.1.1-rc.2 release. Separate npm bundle distribution is
deferred and currently unavailable.
The bundle provides four agent-scoped tools (cortex_search,
cortex_related, cortex_impact, and cortex_rules) and five Cortex behavior
skills (change-impact, context-review, pattern-review, repo-research,
and using-cortex). Retrieval is local, repository-scoped, explicit, and
user-controlled. The integration does not automatically initialize, update,
or watch a repository.
V2 proactive/assistive retrieval remains planned and experimental; it is not included in Cortex 2.6.0. See the V1-to-V2 integration plan for details.
MIT