Cortex Docs: One Config for OpenAPI SDKs, Interactive Docs and an MCP Server

The problem Cortex Docs solves, and for whom

Most teams with a public API end up maintaining three artifacts that drift apart: a documentation site, client libraries per language, and some retrieval layer so an AI agent can answer questions about the API. Each has its own tool, its own config, and its own release process. Cortex Docs collapses that into one project configuration. The README states the project "turns API specifications and Markdown into typed SDKs, interactive documentation, and an MCP server from one project configuration."

The target reader is a platform or developer-experience engineer who already has a spec file, not someone writing API docs from scratch. The README's own comparison table frames the alternative as a "split toolchain" where SDK, documentation and MCP generators are configured separately and coordinated by hand. Cortex's claim is that you declare your sources once and one command produces every output.

That framing also sets the boundary. If your API contract lives in a wiki page or in the heads of the backend team, Cortex has nothing to read. It is a consumer of specifications, not an authoring tool.

How the generation pipeline is put together

Everything starts at cortex.config.yml. Relative paths resolve from the directory containing that file, which means the config is portable as long as you keep it next to your specs. A sources list declares each input with a type (openapi-spec, asyncapi-spec, graphql-spec and so on), a spec path, an optional intro Markdown file, and a languages block naming the target language and the package name to emit.

The repository layout supports the README's description of the pipeline. The monorepo has separate workspaces for core, codegen, mcp-gen and cli, and the build:cli script compiles them in that order: core, then codegen, then mcp-gen, then cli. So parsing and config handling sit in core, SDK and documentation emission in codegen, MCP server emission in mcp-gen, and the command surface in cli.

One detail worth noting in the README's dry-run output: a single generated SDK can carry multiple protocols at once. The sample shows "typescript [REST + WS + GraphQL + OpenRPC]" pointing at one output directory. That is a different model from generators that produce one client per spec, and it is the reason the config groups languages under each source rather than listing output targets globally.

Installing the CLI and running a first generation

The README's "Try Cortex in 60 seconds" section is the shortest path. It assumes Node.js 20 or later and npm 10 or later, both listed under Requirements. The first block creates a scratch directory, installs the CLI globally from npm, scaffolds a sample project, validates the config, and prints the generation plan without writing files.

mkdir petstore
cd petstore
npm install --global @cortex-docs/cli
cortex init petstore
cortex validate
cortex generate --dry-run

The README shows what the dry run prints: a checkmark per parsed source (AsyncAPI, GraphQL, OpenRPC, OpenAPI), a languages line, and one arrow per planned output such as generated/typescript/petstore-typescript-client-sdk and generated/mcp-server. Read this list before generating anything, because it is the only place the tool tells you what it intends to write.

The second block performs the real generation and starts the local preview server.

cortex generate
cortex docs serve

According to the README, the preview listens on http://localhost:3012 and stops with Ctrl+C. That port is fixed in the documentation; nothing in the README describes a flag to change it.

Once you move past the sample, the config file is where the real work is. The README gives this shape for a source entry:

sources:
  - title: REST API
    type: openapi-spec
    spec: ./specs/openapi.yaml
    intro: ./docs/rest.md
    languages:
      - language: typescript
        package_name: '@my-org/my-api'

The intro key points at Markdown that is merged into the generated documentation for that source, which is how the README's promise of combining Markdown and API references is actually wired.

Customization means overriding Eta templates, and that is a commitment

Cortex does not expose a plugin API for output shape. The README says you customize generated output with "sparse Eta template overrides," and the comparison table describes the workflow as overriding "only the required Eta templates."

Sparse overrides are a reasonable default: you copy the template you want to change, edit it, and leave the rest alone. The cost is that you now own a fork of that template. When an upstream release changes the template's inputs, your override does not automatically follow. The README does not describe any compatibility guarantee between template overrides and later releases, and it does not document a migration path for overrides. If you plan to override more than a couple of templates, treat the upgrade cost as ongoing rather than one-time.

For teams that only need package names, logos, colors and custom head HTML, the config covers it without touching templates. The README's config example includes logo, theme, primaryColor and a custom_head_html block for injecting a theme-color meta tag and a stylesheet link.

Where Cortex Docs is the wrong tool

The most obvious failure mode is spec quality. Cortex validates that a spec parses, and the dry run reports each source as parsed. It does not follow that the resulting SDK is pleasant to use. A spec with generic operation IDs, untyped free-form objects or missing response schemas will produce a client that is technically correct and practically annoying. Cortex amplifies whatever is in the spec, including its weaknesses.

The second limitation is language coverage versus language quality. The README lists eleven target languages: TypeScript, Python, Go, Java, Kotlin, Ruby, PHP, C#, Rust, C++ and C. The repository's own Dockerfile shows what it takes to verify that breadth: a base image carrying Node.js 22, Python 3, Go 1.23, Java 17 with Maven and Gradle, Ruby, PHP with Composer, .NET 8 and Rust, all so the SDK integration tests can compile each generated client. That is a substantial test matrix, and it is also a signal that a single release can regress in one language without affecting the others. If you ship in one language only, you are paying attention to a project whose surface is much wider than your use.

The third case is organizational rather than technical. If your docs, SDKs and agent context are owned by different teams with different release cadences, a single config file makes those cadences collide. Cortex assumes one team can review one publish plan.

How it differs from a spec-first generator like OpenAPI Generator

OpenAPI Generator is the obvious reference point, and the difference is scope rather than quality. OpenAPI Generator takes an OpenAPI document and emits client libraries, server stubs and documentation, with a large catalogue of generators and a long history of community-contributed templates.

Cortex's inputs are wider: the README names OpenAPI, AsyncAPI, GraphQL, Protocol Buffer, OpenRPC and Markdown, and the dry-run output shows a single TypeScript SDK combining REST, WebSocket, GraphQL and OpenRPC sources. OpenAPI Generator's model is one generator run per input document. Cortex's model is one project configuration that fans out to SDKs, a static HTML documentation site, and an MCP server.

That last output is the real divergence. Cortex generates an MCP server with "typed tools, embedded specifications, SDK guides, and project documentation" for AI agents, and the config can add Markdown pages and SDK guides to it. OpenAPI Generator has no equivalent output. If you do not care about agents consuming your API, that part of Cortex is dead weight you still configure around.

The trade-off runs the other way too. OpenAPI Generator has years of accumulated generator variants and community templates; Cortex is at v0.1.35, released 2026-09-22, and the README does not describe a plugin ecosystem.

Licence, maintenance and what an upgrade actually costs

Cortex is MIT licensed, and the repository carries a LICENSE file plus a THIRD_PARTY_LICENSES file. MIT is permissive, so generated output and template overrides are yours to ship. That is a statement about the project's licence, not legal advice about your own dependency obligations; the THIRD_PARTY_LICENSES file is the place to look for what the toolchain pulls in.

The repository is not archived, and the last push was on 2026-09-22, the same day as the v0.1.35 release. The version number is the more useful signal here: 0.1.x means the configuration schema and the template inputs can still move between releases. The README documents cortex init, cortex validate, cortex generate with a --dry-run flag, and cortex docs serve, but it does not document a rollback path for generated files that have already been published to a registry.

Upgrade cost therefore splits in two. If you use the config as-is, upgrading means reinstalling the CLI and re-running cortex generate. If you maintain Eta overrides, upgrading means diffing your overrides against the new templates before you regenerate, because nothing in the README promises that your overrides will still apply cleanly.

Editorial conclusion

Adopt Cortex Docs if you already keep a machine-readable spec in version control and want SDKs, a browsable reference and an MCP server to move together under one config file. Skip it if your API surface only exists as prose, or if you need a generator with a long release history behind it. Before committing, run cortex generate --dry-run on your own specs and read the planned output list, then check whether every language you ship is in the languages block, because the README does not document a rollback path once generated files are published.

Frequently asked questions

Official sources

1. cortex-docs/cortex on GitHub
2. License: MIT
3. Project website
4. README
5. Releases