ContextMCP is configured through a single config.yaml file in your project root.

Overview

The configuration file has four main sections:

vectordb - Where to store embeddings
embeddings - Which model to use
sources - What documentation to index
chunking - How to split content

Full Example

vectordb:
  provider: pinecone
  indexName: my-company-docs
  namespace: production
  pinecone:
    cloud: aws
    region: us-east-1

embeddings:
  provider: openai
  model: text-embedding-3-large
  dimensions: 3072

sources:
  - name: main-docs
    displayName: "Documentation"
    type: github
    repository: myorg/docs
    branch: main
    parser: mdx
    baseUrl: https://docs.example.com
    skipDirs:
      - node_modules
      - .git

  - name: api-reference
    displayName: "API Reference"
    type: github
    repository: myorg/api
    path: openapi
    parser: openapi
    baseUrl: https://docs.example.com/api

chunking:
  maxChunkSize: 2000
  minChunkSize: 250
  idealChunkSize: 1000

reindex:
  clearBeforeReindex: true
  batchSize: 100

Vector Database

Currently supports Pinecone. Your embeddings are stored here.

vectordb:
  provider: pinecone
  indexName: my-docs # Your Pinecone index name
  namespace: production # Optional: namespace within index
  pinecone:
    cloud: aws # aws or gcp
    region: us-east-1 # Your Pinecone region

Configure the model used to generate vector embeddings. ContextMCP supports five providers — OpenAI, Google Gemini, Cohere, Voyage AI, and Ollama (local). Pick whichever you prefer; you only need the API key for the provider you choose (Ollama needs none).

OpenAI (default)

embeddings:
  provider: openai
  model: text-embedding-3-large # or text-embedding-3-small
  dimensions: 3072 # 3072 for large, 1536 for small

Requires OPENAI_API_KEY.

Cost note: text-embedding-3-large costs ~$0.13 per 1M tokens. For a typical docs site (~500 files), expect ~$0.50-1.00 per full reindex.

Google Gemini

embeddings:
  provider: gemini
  model: gemini-embedding-2-preview
  dimensions: 3072

Requires GEMINI_API_KEY.

Cohere

embeddings:
  provider: cohere
  model: embed-v4.0
  dimensions: 1536

Requires COHERE_API_KEY.

Voyage AI

embeddings:
  provider: voyage
  model: voyage-4
  dimensions: 1024

Requires VOYAGE_API_KEY.

Local Embeddings with Ollama

Run embeddings fully offline with a local Ollama server — no API key, no per-token cost.

embeddings:
  provider: ollama
  model: nomic-embed-text # or mxbai-embed-large, etc.
  dimensions: 768 # must match the model's output dimension
  ollama:
    baseUrl: http://localhost:11434 # optional, this is the default

Pull the model first: ollama pull nomic-embed-text.

Worker note: The Cloudflare worker generates query embeddings at request time, and Workers cannot reach localhost. To serve an Ollama-indexed corpus, expose your Ollama server on a reachable URL and set OLLAMA_BASE_URL in the worker — or run the self-hosted Node server (see the self-hosting docs).

Provider Comparison

Provider	`model`	`dimensions`	Required env var
`openai`	`text-embedding-3-large`	`3072`	`OPENAI_API_KEY`
`gemini`	`gemini-embedding-2-preview`	`3072`	`GEMINI_API_KEY`
`cohere`	`embed-v4.0`	`1536`	`COHERE_API_KEY`
`voyage`	`voyage-4`	`1024`	`VOYAGE_API_KEY`
`ollama`	`nomic-embed-text`	`768`	(none — local)

Note: The dimensions value must match the model you choose, and the Pinecone index must be created with the same dimension. If you switch providers or models with a different dimension, recreate the index.

The Cloudflare worker selects the provider at runtime via the EMBEDDING_PROVIDER, EMBEDDING_MODEL, and EMBEDDING_DIMENSIONS variables in wrangler.jsonc — keep these in sync with your config.yaml.

Sources

Define where your documentation lives. You can have multiple sources.

GitHub Repository

sources:
  - name: docs # Unique identifier
    displayName: "My Docs" # Human-readable name
    type: github
    repository: owner/repo # GitHub repo
    branch: main # Optional, defaults to main
    path: docs/ # Optional, subdirectory
    parser: mdx # mdx, markdown, openapi, or html
    baseUrl: https://docs.example.com
    skipDirs:
      - node_modules
      - .git
      - images
    skipFiles:
      - CHANGELOG.md

GitLab Repository

Clone from gitlab.com or a self-hosted GitLab instance. Set GITLAB_TOKEN for private projects.

sources:
  - name: docs
    displayName: "My Docs"
    type: gitlab
    repository: mygroup/mysubgroup/docs # group(s)/project
    branch: main
    path: docs/ # optional subdirectory
    parser: mdx
    baseUrl: https://docs.example.com
    gitlabHost: gitlab.example.com # optional, defaults to gitlab.com

Parser Types

Parser	Use For	Features
`mdx`	MDX/Markdown docs	Extracts frontmatter, preserves code blocks
`markdown`	Plain markdown, READMEs	Simple parsing, language hints
`openapi`	Swagger/OpenAPI specs	Generates docs from API definitions
`html`	Raw `.html`/`.htm` docs	Strips boilerplate, converts to Markdown

Language Hints

When indexing SDK repositories, add a language hint:

- name: python-sdk
  repository: myorg/python-sdk
  parser: markdown
  language: python # Helps AI understand context

Chunking

Control how documents are split for indexing.

chunking:
  maxChunkSize: 2000 # Maximum characters per chunk
  minChunkSize: 250 # Minimum (avoids tiny chunks)
  idealChunkSize: 1000 # Target size

Note: ContextMCP uses AST-aware chunking. Code blocks and tables are never split mid-content, regardless of size limits.

Reindex Settings

reindex:
  clearBeforeReindex: true # Clear index before reindexing
  batchSize: 100 # Vectors uploaded per batch

Using YAML Anchors

For shared configuration across sources:

x-common-skip: &commonSkip
  - node_modules
  - .git
  - dist
  - __pycache__

sources:
  - name: docs
    skipDirs: *commonSkip

  - name: sdk
    skipDirs: *commonSkip

Configuration