Context Engine

Data Source Providers

Connect any API or data source to LeanCTX using config-based providers. Zero code, just TOML.

Config-based providers let you connect any REST API to LeanCTX without writing a single line of Rust. Drop a TOML or JSON file into your providers directory, and LeanCTX automatically discovers and registers it.

Your AI agent can then query live data from GitHub issues, Jira tickets, database records, or any API — all through the same ctx_provider tool.

Quick Start

1

Create the providers directory

shell
$ mkdir -p ~/.config/lean-ctx/providers
2

Drop a TOML config file

~/.config/lean-ctx/providers/github.toml
[provider]
id = "github"
name = "GitHub Issues"
base_url = "https://api.github.com"
[auth]
type = "bearer"
token_env = "GITHUB_TOKEN"
[[resources]]
name = "issues"
path = "/repos/{owner}/{repo}/issues"
[resources.response]
items_path = "[]"
[resources.response.fields]
title = "title"
id = "number"
description = "body"
3

Restart LeanCTX — your provider is live

shell
$ lean-ctx stop && lean-ctx start
→ Discovered provider: github (1 resource)

Configuration Reference

SectionFieldTypeDescription
[provider]idstringUnique identifier (used in ctx_provider query)
namestringHuman-readable display name
base_urlstringAPI base URL (no trailing slash)
descriptionstring?Optional description shown in ctx_provider list
[auth]typeenumbearer, api_key_header, api_key_query, basic, header, none
token_envstring?Environment variable name for bearer token
key_envstring?Environment variable name for API key
header_namestring?Custom header name (for api_key_header / header)
username_envstring?Environment variable for Basic auth username
password_envstring?Environment variable for Basic auth password
[[resources]]namestringResource name (used in ctx_provider query)
pathstringURL path with {param} placeholders
methodstring?HTTP method (default: GET)
[resources.response]items_pathstringDot-notation path to items array (e.g. data.issues[])
[resources.response.fields]titlestringJSON path for item title
idstringJSON path for item ID
descriptionstring?JSON path for item body/description

Authentication

Five authentication methods are supported out of the box. Secrets are read from environment variables at runtime — never stored in config files.

TypeHeader SentConfig Fields
bearerAuthorization: Bearer $TOKENtoken_env
api_key_headerX-Api-Key: $KEY (customizable)key_env, header_name
api_key_queryAppended as ?key=$KEYkey_env, query_param_name
basicAuthorization: Basic base64(user:pass)username_env, password_env
headerCustom header with custom valuekey_env, header_name
noneNo authentication—

Response Extraction

Use dot-notation paths to extract data from JSON responses. Array iteration is supported with [] syntax.

Extraction Examples
# Simple array at root
items_path = "[]" # → response is the array
# Nested object path
items_path = "data.issues[]" # → response.data.issues
# Field mapping with dot-notation
title = "fields.summary" # → item.fields.summary
id = "key" # → item.key

Auto-Discovery

LeanCTX scans two directories for provider configs on startup:

DirectoryScopeFormats
~/.config/lean-ctx/providers/Global providers (available in all projects).toml, .json
.lean-ctx/providers/Project-local providers (scoped to current repo).toml, .json

Built-in Providers

LeanCTX ships with built-in providers that activate automatically when their environment variables are set:

ProviderEnv VariablesResources
GitHubGITHUB_TOKEN, GITHUB_REPOSITORYIssues, Pull Requests, Actions
GitLabGITLAB_TOKEN, GITLAB_HOSTIssues, Merge Requests, Pipelines
JiraJIRA_BASE_URL, JIRA_TOKEN, JIRA_EMAILIssues, Sprints, Projects
PostgreSQLDATABASE_URLTables, Schema, Queries

All provider data flows through the full consolidation pipeline — BM25 index, graph edges, knowledge facts, and session cache. Controlled by providers.auto_index = true (default).

MCP Bridges

Connect external MCP servers as data sources. Each bridge gets a unique ID (mcp:<name>) and supports listing resources, reading individual resources, and listing tools.

~/.config/lean-ctx/config.toml
# HTTP-based MCP server
[providers.mcp_bridges.knowledge-base]
url = "http://localhost:8080"
# Stdio-based MCP server
[providers.mcp_bridges.github-mcp]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
auth_env = "GITHUB_TOKEN"
FieldTypeDescription
urlstring?HTTP endpoint for MCP server (for HTTP transport)
commandstring?Executable for stdio transport
argsstring[]Arguments for the command
auth_envstring?Environment variable for authentication token

Use lean-ctx doctor to validate MCP bridge configuration and connectivity.

Examples

Jira Tickets

~/.config/lean-ctx/providers/jira.toml
[provider]
id = "jira"
name = "Jira"
base_url = "https://your-org.atlassian.net"
[auth]
type = "basic"
username_env = "JIRA_EMAIL"
password_env = "JIRA_TOKEN"
[[resources]]
name = "issues"
path = "/rest/api/3/search?jql=project={project}"
[resources.response]
items_path = "issues[]"
[resources.response.fields]
title = "fields.summary"
id = "key"
description = "fields.description"

Custom REST API

.lean-ctx/providers/internal-api.toml
[provider]
id = "internal"
name = "Internal Service"
base_url = "https://api.internal.company.com"
[auth]
type = "api_key_header"
key_env = "INTERNAL_API_KEY"
header_name = "X-Service-Key"
[[resources]]
name = "deployments"
path = "/v2/deployments?env={environment}"
[resources.response]
items_path = "data.deployments[]"
[resources.response.fields]
title = "service_name"
id = "deploy_id"
description = "status"