---
url: https://toolchain.dbx.studio/guide/mcp.md
---
# MCP (Model Context Protocol)
`@deltabox/toolchain` ships an MCP server that exposes the dbx APIs to AI
harnesses and editors. It is a dependency-free stdio server, so it works with
any MCP client and does not pull the MCP SDK into your project.
```sh
dbx mcp:serve
```
The server exposes one tool per public dbx capability:
| Tool | Runs |
| -------------------- | ------------------------------------------------------------ |
| `dbx_sync` | `dbx sync` (with `check`, `recursive`, `configless`, `only`) |
| `dbx_projects` | `dbx projects` |
| `dbx_providers` | `dbx providers` |
| `dbx_templates` | `dbx template:list` |
| `dbx_template_info` | `dbx template:info` |
| `dbx_changelog` | `dbx changelog` |
| `dbx_migrate` | `dbx migrate` (preview unless `write`) |
| `dbx_project_config` | `dbx project:config` |
| `dbx_tsconfig` | `dbx tsconfig` |
| `dbx_workflow` | `dbx workflow` |
| `dbx_run` | an allowlisted `dbx` command |
Every tool runs the project's own resolved `dbx` binary, so the MCP surface
always matches the CLI version the project pins. Plugin-mode projects work
without a `dbx.config.*` (the server reads the `dbx()` Vite plugin options).
## Install
```sh
dbx mcp:install --provider claude
dbx mcp:install --provider vscode --scope global
dbx mcp:install --provider custom --dir ./tools/mcp
```
`dbx mcp:list` prints the builtin providers and the exact files each one writes:
| Provider | Project config | Skill / instructions |
| ---------- | -------------------- | ----------------------------------------------- |
| `claude` | `.mcp.json` | `.claude/skills/deltabox/SKILL.md` |
| `codex` | `.codex/config.toml` | `.codex/skills/deltabox/SKILL.md` |
| `vscode` | `.vscode/mcp.json` | `.github/instructions/deltabox.instructions.md` |
| `opencode` | `opencode.json` | `.opencode/skills/deltabox/SKILL.md` |
| `pi` | `.pi/mcp.json` | `.pi/skills/deltabox/SKILL.md` |
| `custom` | `
/mcp.json` | `/deltabox/SKILL.md` |
`--scope global` writes to the provider's user profile instead
(`~/.claude.json`, `~/.codex/config.toml`, `~/.config/opencode/opencode.json`,
...). `--no-skills` writes only the MCP config, and `--json` prints the exact
paths that were written.
The VS Code extension exposes the same flow from **Install MCP server + skill...**
(and the Home view's Quick Actions).
## Skills
`dbx skills` installs the **official dbx toolchain skill** without the MCP
server. The skill is documentation-only: it tells the agent to read
[`https://toolchain.dbx.studio/llms.txt`](https://toolchain.dbx.studio/llms.txt)
and follow the relevant docs page before answering or editing files. It also
tells the agent to inspect the project first:
* `dbx.config.*` / `vite.config.*` (with the `dbx()` plugin) and
`.vscode/settings.json` (`deltabox.toolchain.enabled`) to see whether the
toolchain is enabled.
* `.dbx/toolchain/projects.json` for the project graph and config locations, and
`.dbx/toolchain/manifest.json` for managed files.
* The enabled `toolchain` sections, so conventions such as commitlint/changelog
commit messages are respected.
```sh
dbx skills # list the install status per agent
dbx skills --official # install for every builtin agent
dbx skills --official --provider claude # one agent
dbx skills --official --provider vscode --scope global
dbx skills --official --provider custom --dir ./tools/agent
dbx skills --official --force # overwrite an existing skill
```
Installs are idempotent: an existing skill file is left untouched unless
`--force` is passed, so local edits are preserved. `--json` prints the status or
write results.
### Automatic installation
Opt in through `toolchain.mcp.skills`; `dbx sync` (and `dbx watch`) then adds the
skill wherever it is missing:
```ts
export default defineConfig({
toolchain: {
mcp: {
skills: {
agents: ['claude', 'vscode'],
scope: 'project',
},
},
},
});
```
| Option | Meaning |
| --------- | --------------------------------------------------------------- |
| `agents` | Agent id or ids (default: every builtin provider). |
| `scope` | `project` (default) or `global`. |
| `dir` | Custom directory (with `agents: ['custom']`). |
| `force` | Overwrite existing files (default: `false`). |
| `enabled` | Set `false` to keep the section configured but stop installing. |
The skill paths mirror the MCP provider table above, using the
`deltabox-toolchain` stem (for example
`.claude/skills/deltabox-toolchain/SKILL.md`). The VS Code extension adds an
**Install official skill...** prompt action alongside the MCP installer.
### Programmatic API
```ts
import {
checkSkill,
installOfficialSkill,
installSkill,
resolveMcpSkillsConfig,
} from '@deltabox/toolchain/mcp';
checkSkill({ agent: 'claude', cwd }); // { path, exists }
installOfficialSkill({ agent: 'claude', cwd }); // writes only when missing
installSkill({ agent: 'vscode', scope: 'global', force: true });
resolveMcpSkillsConfig(config); // the configured agents/scope, or undefined
```