# MCP JSON-RPC Source: https://docs.btca.dev/api-reference/cloud/mcp /api-reference/openapi.cloud.json POST /api/mcp Invokes MCP tools such as `listResources`, `ask`, `addResource`, and `sync`. The hosted endpoint supports request/response MCP tool calls over `POST /api/mcp`. Long-lived SSE notification streams are disabled on the cloud deployment. # API Reference Source: https://docs.btca.dev/api-reference/introduction Local server and cloud APIs for btca btca exposes two HTTP surfaces: * **Local server API**: runs on your machine, no authentication required. * **Cloud API**: hosted services that require a Bearer API key. Use the navigation to browse endpoints. Each page is backed by OpenAPI and includes live schemas. ## Authentication * Local server: no auth. * Cloud API: `Authorization: Bearer `. # Clear cached resources Source: https://docs.btca.dev/api-reference/local/clear /api-reference/openapi.local.json POST /clear Clears all locally cached resource clones. # Get config Source: https://docs.btca.dev/api-reference/local/config /api-reference/openapi.local.json GET /config Returns the currently loaded configuration summary, including model/provider and runtime settings like `maxSteps`. # Update provider model Source: https://docs.btca.dev/api-reference/local/config-model /api-reference/openapi.local.json PUT /config/model Updates the active provider and model. For `openai-compat`, include `providerOptions` with `baseURL` and `name` so the server can construct the OpenAI-compatible provider. The `model` field remains required and is used as the model ID when sending requests. # Add a resource Source: https://docs.btca.dev/api-reference/local/config-resources /api-reference/openapi.local.json POST /config/resources Adds a git or local resource to the current config. # Remove a resource Source: https://docs.btca.dev/api-reference/local/config-resources-delete /api-reference/openapi.local.json DELETE /config/resources Removes a resource by name. # Health Source: https://docs.btca.dev/api-reference/local/health /api-reference/openapi.local.json GET / Simple service health check. # List providers Source: https://docs.btca.dev/api-reference/local/providers /api-reference/openapi.local.json GET /providers Shows supported providers and which ones are connected. # Ask a question Source: https://docs.btca.dev/api-reference/local/question /api-reference/openapi.local.json POST /question Runs a one-shot query against the configured resources. # Ask a question (stream) Source: https://docs.btca.dev/api-reference/local/question-stream /api-reference/openapi.local.json POST /question/stream Streams server-sent events for the query lifecycle. ## Events SSE format: ```txt theme={null} event: data: ``` Event types: * `meta` * `reasoning.delta` * `text.delta` * `tool.updated` * `done` * `error` ### done The final event is `done`. It always includes `text`, `reasoning`, and `tools`, and may include optional `usage` and `metrics`: ```json theme={null} { "type": "done", "text": "final answer", "reasoning": "full reasoning", "tools": [], "usage": { "inputTokens": 1234, "outputTokens": 456, "reasoningTokens": 120, "totalTokens": 1690 }, "metrics": { "timing": { "totalMs": 5321, "genMs": 2710 }, "throughput": { "outputTokensPerSecond": 168.3, "totalTokensPerSecond": 623.6 }, "pricing": { "source": "models.dev", "modelKey": "openai/gpt-4o-mini", "ratesUsdPerMTokens": { "input": 0.14, "output": 0.54 }, "costUsd": { "input": 0.000173, "output": 0.000246, "total": 0.000419 } } } } ``` Notes: * Pricing is best-effort and may be omitted. * Pricing rates are USD per 1M tokens from `https://models.dev/api.json`. # Reload config Source: https://docs.btca.dev/api-reference/local/reload-config /api-reference/openapi.local.json POST /reload-config Reloads configuration from disk and returns the active resource names. # List resources Source: https://docs.btca.dev/api-reference/local/resources /api-reference/openapi.local.json GET /resources Lists all configured resources from the active config. # Authentication Source: https://docs.btca.dev/guides/authentication Connect and manage local provider authentication ## Local provider auth (btca-server) btca reads credentials from OpenCode's auth storage: * macOS/Linux: `~/.local/share/opencode/auth.json` * Windows: `%APPDATA%/opencode/auth.json` Supported providers: * `opencode` (API key) * `openrouter` (API key) * `openai` (OAuth, no API keys) * `github-copilot` (OAuth device flow) * `openai-compat` (optional API key) * `anthropic` (API key) * `google` (API key or OAuth) * `minimax` (API key) Environment variable overrides: * `OPENCODE_API_KEY` (for provider `opencode`) * `OPENROUTER_API_KEY` (for provider `openrouter`) * `MINIMAX_API_KEY` (for provider `minimax`) ### Connect or disconnect ```bash theme={null} btca connect btca disconnect btca wipe ``` `btca connect` performs OAuth for `openai` and `github-copilot`, prompts for API keys when required, and falls back to `opencode auth --provider ` for other providers. `btca wipe` removes BTCA config files in the current directory and global BTCA config files (with a confirmation prompt unless `--yes` is passed). For `github-copilot`, btca uses device flow OAuth and opens a browser prompt to complete the sign-in. GitHub Copilot model availability can vary by endpoint, account, and organization policy. Public model catalogs may list models that the Copilot chat API still rejects for your specific token or plan, so treat Copilot model selection as best-effort rather than guaranteed. For `openai-compat`, `btca connect` also collects the required provider details: * **Base URL** (required): the root URL of your OpenAI-compatible server. The AI SDK appends its own endpoint paths, so btca must know the base URL to send requests to the correct host. * **Provider name** (required): the identifier the AI SDK uses to namespace requests for this OpenAI-compatible provider. * **Model ID** (required): the model to use for requests; stored in `btca.config.jsonc` as `model`. * **API key** (optional): only if your server requires authentication; stored in OpenCode auth. # CLI Reference Source: https://docs.btca.dev/guides/cli-reference All btca commands and what each one does ## Global options These options apply to local CLI commands. | Option | Description | | ---------------- | ----------------------------------------------------------- | | `--server ` | Use an existing server (health checked). | | `--port ` | Port for an auto-started server (default `0`, OS-assigned). | | `--no-tui` | Use REPL instead of TUI. | | `--no-thinking` | Hide reasoning output (REPL and `ask`). | | `--no-tools` | Hide tool traces (REPL and `ask`). | | `--sub-agent` | Clean output (no reasoning or tool traces). | ## `btca` Launches the TUI by default. Use `--no-tui` for the REPL. Passing an unknown top-level command now exits with `error: unknown command ''` and a non-zero status code, and may include a suggestion for a known command. REPL commands: * `/help` shows help. * `/resources` lists resources. * `/clear` clears session resources. * `/quit` or `/exit` exits. The REPL supports `@resource` mentions. TUI command palette (`/`): * `/connect` configures provider and model. * `/add` opens the add-resource wizard. * `/clear` clears chat history. * `/resume` opens thread resume. * `/new` is an alias for `/clear`. * `/copy` copies the latest user question and assistant response. * `/copy-all` copies the full thread (all user and assistant messages). TUI keyboard shortcuts: * `Enter` sends message. * `Escape` cancels streaming response (press twice to confirm). * `Ctrl+C` clears input or quits. * `Ctrl+Q` quits. * `Tab` autocompletes commands/mentions. * `Up/Down` navigates palettes/history. ## `btca add [url-or-path]` Adds a git repo, local directory, or npm package resource. Options: * `-g, --global` sets the flag, but target resolution still depends on whether a project config exists. * `-n, --name ` sets a resource name. * `-b, --branch ` sets a branch (default `main`). * `-s, --search-path ` sets one or more search paths. * `--notes ` sets special notes. * `-t, --type ` forces the resource type. Behavior: If no argument is provided, the CLI starts an interactive wizard. When `--type` is omitted, it auto-detects git URL vs local path vs npm reference. GitHub URLs are normalized to the base repo. Local paths are resolved to absolute paths. npm references accept package specs (`react`, `@types/node`, `npm:react`) and npmjs package URLs. Examples: ```bash theme={null} # Git resource btca add https://github.com/sveltejs/svelte.dev -n svelte-docs -t git -b main -s apps/svelte.dev # Local resource btca add -n my-docs -t local /absolute/path/to/docs # npm resource btca add npm:@types/node@22.10.1 -n node-types -t npm ``` ## `btca reference ` Clones a git repository into `./references/` for local reference use. Behavior: * Destination is always `references/`, where `` is derived from the clone target. * If destination already exists, the command fails and does not overwrite. * In a git repository, it adds `references/` to `.git/info/exclude` (local-only, not committed) if missing. * Outside a git repository, clone still succeeds and prints a warning that exclude was not updated. * Prints optional copy-paste snippets for `AGENTS.md` and `CLAUDE.md` to let agents use `references/` as read-only supplemental context. Example: ```bash theme={null} btca reference https://github.com/sveltejs/svelte.git ``` ## `btca remove [name]` Removes a resource by name. If omitted, it opens an interactive picker. Options: * `-g, --global` sets the flag, but is not a strict global override. ## `btca resources` Lists all configured resources. ## `btca ask` Asks a one-shot question with streaming output. Options: * `-q, --question ` is required. * `-r, --resource ` can be repeated. * `--no-thinking`, `--no-tools`, `--sub-agent` control output detail. Behavior: `@resource` mentions are resolved and merged with `-r` flags. Mentions are stripped from the query text before sending. If no resources are provided, it uses all configured resources. Uses the `/question/stream` SSE endpoint. You can also pass raw HTTPS git URLs directly instead of a configured resource name. These URLs are treated as one-off resources: * They are normalized (for example, GitHub `.../blob/main/...` URLs become the base repo URL). * They use a short-lived cache key derived from a hash of the URL. * They are cloned into a temporary folder under `.tmp` and removed after the request finishes. * Branch detection tries `main`, then `master`, then `trunk`, then `dev`. * If none of those branches exist, the request fails with an instruction to add the repo as a named resource instead. You can also pass one-off npm references directly: * `npm:` (for example `npm:react`) * `npm:@` (for example `npm:@types/node@22.10.1`) * npmjs URLs (for example `https://www.npmjs.com/package/react`) These references are hydrated into temporary resources and removed automatically after the request. Examples: ```bash theme={null} # Normal configured resource ask btca ask -r svelte -q "How do runes work in Svelte 5?" # Anonymous one-off git repo ask btca ask -r https://github.com/sveltejs/svelte -q "Where is the implementation of writable stores?" # Anonymous one-off npm package ask btca ask -r npm:react@19.0.0 -q "How is useTransition exported?" ``` ## `btca connect` Configures provider and model. Options: * `-g, --global` targets the global config if no project config exists. * `-p, --provider ` sets the provider. * `-m, --model ` sets the model. Behavior: When provider and model are provided, it updates the config directly. Otherwise, it walks an interactive provider selection (connected providers first), then model selection. If auth is required, it prompts for credentials. Current curated model choices in the interactive flow: * `openai`: `gpt-5.3-codex-spark`, `gpt-5.4` * `opencode`: `claude-haiku-4-5`, `claude-sonnet-4-6`, `gemini-3-flash`, `glm-4.7`, `kimi-k2.5`, `gpt-5.4`, `gpt-5.3-codex-spark` For `github-copilot`, model selection is best-effort. GitHub Copilot may reject model IDs that appear in public model catalogs depending on the specific API endpoint, account, or org policy. For `openai-compat`, the interactive flow additionally prompts for: * Base URL (required): root URL of your OpenAI-compatible server. * Provider name (required): AI SDK provider identifier. * Model ID (required): saved as `model` in `btca.config.jsonc`. * API key (optional): only if your server requires auth, stored in OpenCode auth. ## `btca status` Shows current btca status. Output includes: * selected model * selected provider * selected model source (`project`, `global`, or `default`) * selected provider source (`project`, `global`, or `default`) * whether the selected provider is authenticated * resources from `~/.config/btca/btca.config.jsonc` * resources from `./btca.config.jsonc` (if the file exists) * installed btca version and latest npm version * update hint if your version is behind If an update is available, it prints: ```bash theme={null} Update available: run "bun add -g btca@latest" ``` ## `btca disconnect` Disconnects provider credentials. Options: * `-p, --provider ` selects a provider to disconnect. Behavior: If omitted, it opens an interactive picker. ## `btca skill` Runs the skills.sh installer for the btca CLI skill (interactive). ## `btca init` Project setup wizard. Options: * `-f, --force` overwrites existing config. Behavior: Creates `btca.config.jsonc` and prompts for storage mode (`local` `.btca/` or global). If local storage is selected, it also handles `.gitignore` updates for `.btca/`. ## `btca clear` Clears all locally cloned resources. ## `btca wipe` Permanently deletes BTCA config files for the current directory and global config. Options: * `-y, --yes` skips the interactive confirmation prompt. Behavior: * Targets `./btca.config.jsonc`. * Targets `~/.config/btca/btca.config.jsonc`. * Prints removed, missing, and failed paths. * Shows a confirmation prompt unless `--yes` is passed. ## `btca serve` Starts the local server. Options: * `-p, --port ` sets the port (default `8080`). ## `btca mcp` Runs the local MCP server over stdio by default. Subcommands: * `btca mcp local` scaffolds editor config for local stdio MCP. Behavior: * Starts (or reuses) the local server and exposes MCP tools over stdin/stdout. * Intended for agent configs that support stdio transport. Tools: * `listResources` - list local resources. * `ask` - ask a question against local resources, HTTPS git URLs, or npm references. # Configuration Source: https://docs.btca.dev/guides/configuration Local config files, defaults, and validation limits ## Local config: `btca.config.jsonc` Locations: * Project: `./btca.config.jsonc` * Global: `~/.config/btca/btca.config.jsonc` Behavior: * JSONC is supported (comments and trailing commas). * Global is loaded first, project overrides conflicts. * If a project config exists, `dataDirectory` resolves relative to the project. * Resources are stored in `${dataDirectory}/resources`. Example: ```jsonc theme={null} { "$schema": "https://btca.dev/btca.schema.json", "provider": "opencode", "model": "claude-haiku-4-5", "maxSteps": 40, "dataDirectory": ".btca", "providerOptions": { // OpenAI-compatible providers (e.g., LM Studio) "openai-compat": { // Base URL of your OpenAI-compatible server "baseURL": "http://localhost:1234/v1", // Provider name used by the AI SDK "name": "lmstudio" } }, "resources": [ { "type": "git", "name": "svelte", "url": "https://github.com/sveltejs/svelte.dev", "branch": "main", "searchPath": "apps/svelte.dev", "specialNotes": "Focus on docs content" }, { "type": "npm", "name": "reactNpm", "package": "react", "version": "latest" } ] } ``` OpenAI-compatible config requirements: * `providerOptions.openai-compat.baseURL` (required) tells btca where to send requests. * `providerOptions.openai-compat.name` (required) is the provider identifier used by the AI SDK. * `model` (required) must match a model ID your server exposes. * The API key (if required) is stored in OpenCode auth, not in this config. Defaults if the global config is missing: * `provider`: `opencode` * `model`: `claude-haiku-4-5` * `providerTimeoutMs`: `300000` * `maxSteps`: `40` * Default resources: `svelte`, `tailwindcss`, `nextjs` If `dataDirectory` is missing and a legacy `.btca/` exists, the project config is migrated to use `.btca`. ## Validation limits * Resource name: max 64 chars, regex `^@?[a-zA-Z0-9][a-zA-Z0-9._-]*(/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$`, no `..`, no `//`, no trailing `/` * Branch: max 128 chars, regex `^[a-zA-Z0-9/_.-]+$`, must not start with `-` * Search path: max 256 chars, no `..`, no absolute paths, no newlines * npm package field: must be a valid npm package name (for example `react` or `@types/node`) * npm version/tag field: optional, must not contain spaces or `/` * Special notes: max 500 chars, no control characters * Question length: max 100,000 chars * Resources per request: max 20 * Git URL: HTTPS only, no embedded credentials, no localhost/private IPs * GitHub URLs are normalized to the base repo. ## Known gaps * One-off HTTPS git URLs (used directly in `btca ask`) are treated as temporary resources. * Anonymous URLs are auto-normalized. * Clones use a short hash-based key and are cleaned up automatically after the request. * btca tries `main`, `master`, `trunk`, then `dev` by default. * If your repo uses a different default branch, add it as a named resource instead of using a one-off URL. * One-off npm references (used directly in `btca ask`) are treated as temporary resources. * Supported formats: `npm:`, `npm:@`, or npmjs package URLs. * Package metadata/readme/page HTML are hydrated into a temporary folder and cleaned up automatically after the request. * `--global` flags exist on several commands, but the effective target is determined by whether a project config exists; there is no strict global override. # MCP Server Source: https://docs.btca.dev/guides/mcp Connect btca to Cursor, Claude Code, Codex, and other MCP-compatible tools [Get your MCP API key](https://btca.dev/app/settings?tab=mcp) Connect btca to Cursor, Claude Code, Codex, and other MCP-compatible tools so they can query the right repos. There are two options: * **Cloud MCP**: Use your btca subscription to give coding tools access to btca-managed resources. * **Local MCP**: Run btca entirely on your machine and expose local resources to coding tools. To scaffold configs automatically, run: * `btca mcp local` For cloud MCP, use the manual config snippets below with your API key. The hosted MCP endpoint is optimized for request/response tool calls. Long-lived SSE notification streams are disabled in cloud deployments. ## Add to `AGENTS.md` Add the following section to your project’s `AGENTS.md`: ```md theme={null} # btca MCP Usage Instructions Use btca whenever a task depends on understanding a repo, docs site, or configured resource more accurately than a generic model can. Use it whenever the user says "use btca", or when you need info that should come from the listed resources. ## Tools The btca MCP server provides these tools: - `listResources` - List all available documentation resources - `ask` - Ask a question about specific resources ## resources The resources available are defined by the end user in their btca dashboard. If there's a resource you need but it's not available in `listResources`, proceed without btca. When your task is done, clearly note that you'd like access to the missing resource. ## Critical Workflow **Always call `listResources` first** before using `ask`. The `ask` tool requires exact resource names from the list. ### Example 1. Call listResources to get available resources 2. Note the "name" field for each resource (e.g., "svelteKit", not "SvelteKit" or "svelte-kit") 3. Call ask with: - question: "How do I create a load function?" - resources: ["svelteKit"] ``` ## Configure your agent Each agent supports both **cloud** (HTTP) and **local** (stdio) MCP servers. Use the examples below to pick the option you want. ### Cursor Cloud (HTTP) in `.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "server-name": { "url": "https://btca.dev/api/mcp", "headers": { "Authorization": "Bearer ak..." } } } } ``` Reference: [Cursor MCP docs](https://cursor.com/docs/context/mcp#using-mcpjson) Local (stdio) in `.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "btca-local": { "command": "bunx", "args": ["btca", "mcp"] } } } ``` ### Codex Cloud (HTTP) in `config.toml`, and add the API key to your environment variables (for example in `.zshenv`): ```toml theme={null} [mcp_servers.btca] bearer_token_env_var = "BTCA_API_KEY" enabled = true url = "https://btca.dev/api/mcp" ``` Reference: [Codex MCP docs](https://developers.openai.com/codex/mcp/) Local (stdio) via CLI: ```bash theme={null} codex mcp add btca-local -- bunx btca mcp ``` ### Claude Code Cloud (HTTP) in the CLI: ```bash theme={null} claude mcp add --transport http better-context https://btca.dev/api/mcp \ --header "Authorization: Bearer ak..." ``` Reference: [Claude Code MCP docs](https://code.claude.com/docs/en/mcp#installing-mcp-servers) Local (stdio) in the CLI: ```bash theme={null} claude mcp add --transport stdio btca-local -- bunx btca mcp ``` ### OpenCode Cloud (HTTP) in `opencode.json`: ```json theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "better-context": { "type": "remote", "url": "https://btca.dev/api/mcp", "enabled": true, "headers": { "Authorization": "Bearer ak..." } } } } ``` Reference: [OpenCode MCP docs](https://opencode.ai/docs/mcp-servers/) Local (stdio) in `opencode.json`: ```json theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "btca-local": { "type": "local", "command": ["bunx", "btca", "mcp"], "enabled": true } } } ``` # Quickstart Source: https://docs.btca.dev/guides/quickstart Install btca, add a codebase, and ask your first grounded repo question ## 1) Install the CLI btca requires Bun. ```bash theme={null} bun add -g btca ``` ## 2) Optional: install the btca CLI skill for guided setup ```bash theme={null} btca skill ``` This runs the `skills.sh` installer (interactive) to install the skill. ## 3) Initialize btca in your project From your repo root: ```bash theme={null} btca init ``` The wizard creates `btca.config.jsonc` for local usage. ## 4) Add a repo ```bash theme={null} btca add -n svelte-dev https://github.com/sveltejs/svelte.dev ``` ## 5) Ask your first question ```bash theme={null} btca ask -r svelte-dev -q "How do I define remote functions?" ``` ## Optional: run the local server ```bash theme={null} btca serve ``` The server starts on port `8080` by default and exposes the local HTTP API. # btca Docs Source: https://docs.btca.dev/index Set up btca for local repo search, cloud workflows, and MCP-powered agents. btca is a codebase research tool with three main entry points: CLI, web app, and MCP. Use these docs to install it, add resources, configure providers, and connect your coding tools. Use the guides to get set up, then jump into the API reference for exact request and response shapes. Install the CLI, add a codebase, and ask your first grounded repo question. Connect providers locally and link cloud API keys. Understand config files, defaults, and validation limits. Browse local and cloud API endpoints. ## Choose your workflow Pick the setup that matches how you work: * **CLI + Local MCP**: best when your code should stay on your machine. * **Web app + Cloud API**: best for saved threads, projects, and cloud-indexed repos.