Skip to content

mcp.md

Latest commit

 

History

History
129 lines (96 loc) · 4.75 KB

mcp.md

File metadata and controls

129 lines (96 loc) · 4.75 KB

MCP Integration

Kinic can be exposed to external agent runtimes as a small tool surface backed by one fixed server identity.
This v1 integration layer is implemented in Rust and exposed only as a local MCP server over stdio. The server identifies itself during MCP initialization as kinic-mcp with the current crate version.

Supported tools

  • memory_list
  • memory_create
  • memory_insert_markdown
  • memory_search
  • memory_search_all
  • memory_show

Successful tool responses are returned as MCP structured content containing JSON objects. This server intentionally uses structured-only success payloads and does not mirror the JSON into text content:

  • memory_list -> {"items":[{"memory_id":"..."}]}
  • memory_create -> {"memory_id":"..."}
  • memory_insert_markdown -> {"memory_id":"...","tag":"...","chunks_inserted":1}
  • memory_search -> {"memory_id":"...","items":[{"score":0.9,"payload":"..."}]}
  • memory_search_all -> {"query":"...","searched_memory_ids":["..."],"failed_memory_ids":[],"join_error_count":0,"items":[{"memory_id":"...","score":0.9,"payload":"..."}]}
  • memory_show -> {"memory_id":"...","name":"...","description":"...","version":"...","dim":384,"owners":["..."],"stable_memory_size":0,"cycle_amount":0,"users":[{"principal_id":"...","role":"writer"}]}

Recommended usage:

  • memory_search: search a memory when the target memory is already known
  • memory_search_all: search across available memories before choosing one
  • memory_show: inspect one memory after selection

Prerequisites

Prepare one Kinic identity on the server side, then set:

export KINIC_TOOL_IDENTITY="<dfx identity name>"
export KINIC_TOOL_NETWORK=local
  • KINIC_TOOL_IDENTITY is required.
  • KINIC_TOOL_NETWORK is optional. Use mainnet or local. Default is local.
  • v1 uses one fixed identity per process.
  • On macOS, Keychain approval may appear when tools serve starts, because the server resolves the identity during startup.
  • After startup, the MCP process reuses that resolved identity for later tool calls instead of re-reading Keychain on every request.
  • If you change the Keychain PEM or switch to a different dfx identity, restart the MCP server to pick up the new identity.

How identity is chosen

The MCP server does not use CLI --identity. Instead, it selects one fixed dfx identity from the process environment:

  • KINIC_TOOL_IDENTITY=<dfx identity name>
  • KINIC_TOOL_NETWORK=local|mainnet

Example:

export KINIC_TOOL_IDENTITY="alice"
export KINIC_TOOL_NETWORK="mainnet"
cargo run -- tools serve

This means:

  • the MCP process runs as alice
  • the network is mainnet when KINIC_TOOL_NETWORK=mainnet
  • the selected identity stays fixed for the life of that MCP process
  • changing to another identity requires editing the environment and restarting the MCP server
  • tools serve does not accept CLI --identity, --ii, --ic, or --identity-path

Run the MCP server

Run the MCP surface over stdio with:

cargo run -- tools serve

This mode is intended for MCP clients that launch a local command. If Keychain access is denied or interrupted, startup fails immediately and MCP tools are not exposed. If you need to change identity or network, change KINIC_TOOL_IDENTITY / KINIC_TOOL_NETWORK and restart the MCP server instead of passing CLI global flags. If startup fails because of configuration or internal server problems, the MCP client receives only a generalized internal error while detailed diagnostics stay in server logs.

MCP clients

Most MCP clients need the same three things:

  • command: cargo
  • arguments: run -- tools serve
  • environment:
    • KINIC_TOOL_IDENTITY=alice
    • KINIC_TOOL_NETWORK=mainnet

Use the MCP tool contract above as the integration boundary instead of parsing CLI text output. If your MCP host cannot set environment variables directly, use a small wrapper script that exports KINIC_TOOL_IDENTITY and KINIC_TOOL_NETWORK before launching cargo run -- tools serve.

n8n

Use n8n's MCP Client Tool or MCP Client node and enter the shared command, args, and environment values there. If your n8n setup supports command-level environment variables, prefer setting them in the node configuration instead of relying on a shell session export.

LM Studio

Use LM Studio as an MCP host and express the same shared command, args, and environment in its MCP server JSON config:

{
  "mcpServers": {
    "kinic": {
      "command": "cargo",
      "args": ["run", "--", "tools", "serve"],
      "env": {
        "KINIC_TOOL_IDENTITY": "alice",
        "KINIC_TOOL_NETWORK": "mainnet"
      }
    }
  }
}

Then allow your local model to call:

  • memory_list
  • memory_create
  • memory_insert_markdown
  • memory_search
  • memory_search_all
  • memory_show