MCP¶

Beta — an MCP server exposing Venkai to any MCP-compatible client (Claude Code, Claude Desktop, and others).

The server runs over stdio and talks to the Venkai API over HTTP. It stores nothing locally: context written through MCP is visible in the dashboard and through the REST API, and vice versa.

flowchart LR
  C["MCP client<br/>(Claude Code, …)"] -->|stdio| S["venkai/mcp/server.py"]
  S -->|HTTPS + Bearer key| A["api.venkai.fr"]
  A --> DB[(store)]

Installation¶

Requires a checkout of the repository and its Python dependencies (Installation).

.mcp.json

{
  "mcpServers": {
    "venkai": {
      "command": "python",
      "args": ["venkai/mcp/server.py"],
      "env": {
        "VENKAI_API_KEY": "vk_live_…",
        "VENKAI_BASE_URL": "https://api.venkai.fr"
      }
    }
  }
}

Variable	Default	Notes
`VENKAI_API_KEY`	—	Falls back to this when a tool call omits `api_key`.
`VENKAI_BASE_URL`	`https://api.venkai.fr`	Point at your own instance if self-hosting.

Every tool also accepts an explicit api_key argument, which takes precedence over the environment. Requests time out after 30 seconds.

Tools¶

All 15 tools. Every one accepts api_key: str = "", omitted below for brevity.

Memory¶

Tool	Signature	Wraps
`venkai_remember`	`(content, project="forge-default", type="fact", agent="hermes-agent", confidence=0.8, importance=0.5)`	`POST /api/memory`
`venkai_recall`	`(query="", project="forge-default", limit=10)`	`GET /api/context/{p}/relevant`
`venkai_decisions`	`(project="forge-default", limit=20)`	`GET /api/context/{p}?type=decision`
`venkai_timeline`	`(project="forge-default", limit=50)`	`GET /api/timeline/{p}`

project defaults to forge-default

Every project-scoped tool defaults to the literal string forge-default. Omit project and your memories land in a shared catch-all namespace rather than failing — pass it explicitly on every call.

Structured writes¶

Tool	Signature
`venkai_store_decision`	`(project, decision, context="", agent="hermes-agent", importance=0.8)`
`venkai_store_workflow`	`(project, workflow_name, steps, outcome="completed", agent="hermes-agent")`

Convenience wrappers that compose a well-formed decision / event memory. venkai_store_decision defaults importance to 0.8 rather than 0.5 — decisions outrank ordinary facts by default.

Inspection¶

Tool	Signature
`venkai_list_projects`	`()`
`venkai_project_summary`	`(project="forge-default")`
`venkai_status`	`(project="")`
`venkai_get_impact`	`()`

Client workflow Experimental¶

Tool	Signature
`venkai_client_accept`	`(client_name, project_name, scope="", budget="", agent="hermes-agent")`
`venkai_client_deliver`	`(project, deliverable, notes="", agent="hermes-agent")`

Opinionated helpers for an agency-style engagement flow. They are thin wrappers over project creation plus typed memories — useful if the workflow matches yours, ignorable otherwise.

Security Experimental¶

Tool	Signature
`venkai_security_check`	`(code, language="python", framework="")`
`venkai_security_gate`	`(code, language="python", framework="", threshold=50)`
`venkai_feedback`	`(project="forge-default", context_id="", rating="positive")`

venkai_security_gate fails when risk_score >= threshold. The underlying scoring has not been validated against a labelled benchmark — do not wire it into a blocking CI step without evaluating it on your own code first.

Usage¶

Once configured, the agent calls the tools directly:

venkai_remember(
  content="We use Postgres, not MongoDB, because the ranking query needs joins.",
  project="billing-service",
  type="decision",
  importance=0.9
)

venkai_recall(query="which database did we pick", project="billing-service", limit=5)

A reliable pattern is to instruct the agent to recall at session start and store on every architectural decision:

At the start of a session, call venkai_recall(project="billing-service")
to load prior context. Whenever a decision is made, record it with
venkai_store_decision(project="billing-service", ...).

Troubleshooting¶

Symptom	Cause	Fix
Every tool returns an auth error	`VENKAI_API_KEY` unset or expired	Check the env block; mint a new key
`recall` returns nothing on a project you wrote to	Wrote to `forge-default` (the default)	Pass `project=` on both calls
Server does not start	`mcp` package missing	`pip install -r venkai/requirements.txt`
Tools hang, then error	API unreachable	`curl $VENKAI_BASE_URL/api/health`
`404 Project not found` on read	Reading a project key that was never written to	Project keys are created on write only

Limitations¶

stdio only. No HTTP or SSE transport.
No MCP resources or prompts. Tools only.
Auth is a static API key in the client config, so it inherits that file's security posture. There is no OAuth flow.