Agents and MCP

This page targets Depsilo v0.9.4. Depsilo offers two complementary agent integrations:

• depsilo init-agent writes human-readable, reviewable package-manager guidance into project instruction files.
• POST /mcp gives MCP-aware clients authenticated, structured, read-only tools.

Do not reuse the bootstrap token

The bootstrap token is only for first-time Setup. Agent instruction files do not need a secret. MCP should use a regular read-only API token created in Admin.

Add project agent instructions

The Docker quick start runs the service container but does not install the depsilo command on the host. Install a CLI version matching the server first. The installer and target below are both pinned to v0.9.4 for Linux and macOS; download the matching archive from the v0.9.4 release on other platforms.

1. Install and check the CLI version

   Terminal

   curl -fsSL https://github.com/depsilo/depsilo/releases/download/v0.9.4/install.sh \
     | DEPSILO_VERSION=v0.9.4 bash
   depsilo version

2. Enter the project and preview the change

   cd my-project
   DEPSILO_URL=http://localhost:23333 depsilo init-agent --dry-run

3. Write the selected file

   DEPSILO_URL=http://localhost:23333 depsilo init-agent

4. Review the diff

   Auto mode detects CLAUDE.md, AGENTS.md, .claude/, .cursor/, or .cursorrules. If it finds no known convention, it creates AGENTS.md. Review and commit only the file you intend to share with the team.

Depsilo owns only the marked block:

<!-- depsilo:start -->
...
<!-- depsilo:end -->

Running the command again updates that block in place and preserves content outside it. Use --format=all to explicitly generate all three formats, --out to select a directory, and --endpoint to override DEPSILO_URL:

depsilo init-agent --format=all --out ./my-project \
  --endpoint http://depsilo.lan:23333

The command first tries the instance’s public GET /api/v1/agent-prompt endpoint. If the service is temporarily unavailable, it uses the template embedded in the CLI. Neither path writes a bootstrap token, API token, or administrator credential into the project.

Connect over MCP

The MCP endpoint is /mcp at the Depsilo service root. v0.9.4 uses the following transport and authentication contract:

Field	Value
URL	http://localhost:23333/mcp
Transport	Streamable HTTP with JSON-RPC 2.0
HTTP method	POST
Header	Authorization: Bearer <token>
Token	A readonly API token created in Admin

This is not a stdio server. There is no separate MCP port and no depsilo mcp subcommand. MCP client configuration schemas differ, so configure the URL and Authorization header above using your client’s supported format.

Create and store a token

Create a readonly API token from the Users page in Admin. The plaintext token is shown only once. Save it in your secret manager, then set it for the current shell:

export DEPSILO_READ_TOKEN='rc_...'

Verify the protocol

initialize

curl -fsS -X POST http://localhost:23333/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DEPSILO_READ_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

A successful response identifies the Depsilo server and negotiates protocol version 2024-11-05.

tools/list

curl -fsS -X POST http://localhost:23333/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DEPSILO_READ_TOKEN" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

tools/call

curl -fsS -X POST http://localhost:23333/mcp \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DEPSILO_READ_TOKEN" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"depsilo_status","arguments":{}}}'

Read-only tools

v0.9.4 exposes these tools. All of them are currently read-only:

Tool	Result
depsilo_status	Service version, health, last-24-hour requests, hit rate, cache, and configured ecosystems
depsilo_doctor	Diagnostic checks with ok, warn, and fail guidance
depsilo_configure	Shell or configuration snippets for one ecosystem; it does not edit client files
depsilo_search	Search the local cache by package name and optional ecosystem
depsilo_recent	Recent cache hit and miss events
depsilo_warmup	Returns only the Admin API request template needed for warmup

warmup does not execute a warmup

A depsilo_warmup result contains executed: false. It does not queue or download packages. It returns a POST /api/v1/admin/cache/warmup template that requires administrator credentials. A write occurs only if an operator reviews and sends that separate request.

Resources and prompt

MCP also exposes:

• depsilo://discover — the running instance’s ecosystems, endpoints, and version.
• depsilo://stats — a snapshot of request counts, hit rate, cache size, and upstream health.
• The setup prompt — project connection guidance for a coding agent.

Discover and read them with resources/list, resources/read, prompts/list, and prompts/get.

Security boundaries

• Use a least-privilege readonly token for MCP and choose an appropriate expiration.
• Do not commit the token to AGENTS.md, CLAUDE.md, .cursorrules, or a repository MCP configuration file.
• Review snippets returned by depsilo_configure, especially host-level APT sources and Docker daemon configuration.
• /mcp requires Bearer authentication. GET /api/v1/agent-prompt and GET /api/v1/discover are public self-description endpoints.