Docs: MCP and scan

MCP and scan

An MCP server for agents that prefer tools to psql, and a scan that checks the result.

sosie mcp

An MCP server over stdio. It talks to the Sosies running on this machine, never to your database or API, so the MCP process holds no credentials and no real values. In Claude Code, the plugin adds it, with a skill; without the skill:

claude mcp add sosie -- npx @sosie/cli mcp

For any other MCP client:

{
  "mcpServers": {
    "sosie": { "command": "npx", "args": ["@sosie/cli", "mcp"] }
  }
}

Start Sosie first, in your own terminal. When none is running, every tool says so, and how to start it.

Tools

Tool From Input Returns
describe Every source entity (optional) Each source by its name, kind and address, with its entities, fields, types, keys, references, and which fields pass
query Postgres, MySQL, SQL Server sql Up to 200 rows per statement as JSON, the row count, and any notice or warning
find MongoDB collection; filter, projection, sort, limit (optional), as JSON Up to 200 documents as Extended JSON
aggregate MongoDB collection, pipeline as a JSON array Up to 200 documents as Extended JSON
request REST path: a path and query, or a link Sosie returned The status and the JSON body of a GET through Sosie, up to 200 items of each list, within 50 s
graphql GraphQL query, variables (optional) The response of a query through Sosie, up to 200 items of each list, within 50 s

Every tool is listed whatever runs; one whose kind is not running says which kinds are. describe lists each source by its name, and a tool takes a source by that name. With one source of its kind, it needs none; with several, it names them and asks for one, so an agent never reads the wrong database without knowing. Sosies of two projects may run at once, their sources listed together; a name both use goes to neither, and the tool says where each is.

The plugin

The same server as a plugin, in the open Agent Plugins format, with a skill that tells the agent how to read through Sosie: start with describe, query by the fakes it saw, and why order, partial matches and computed values follow the real data. Claude Code, GitHub Copilot, VS Code, Cursor, Codex, Kiro and Devin load it.

claude plugin marketplace add monkilabs/sosie
claude plugin install sosie@sosie
Assistant Add the marketplace
Claude Code claude plugin marketplace add monkilabs/sosie, then claude plugin install sosie@sosie
GitHub Copilot copilot plugin marketplace add monkilabs/sosie
Codex codex plugin marketplace add monkilabs/sosie
Cursor Dashboard → Plugins → Team Marketplaces → Import, with monkilabs/sosie

With --scope project on both commands, Claude Code records them in the repository’s .claude/settings.json, so the whole team gets the plugin.

In Claude Code, Copilot CLI and VS Code it also hooks into each session:

  • When a session starts, it tells the agent which Sosies are running and at which addresses. In a project with a sosie.yml and no Sosie running, it tells the agent to ask you to start one, and never to ask for the connection string.
  • When a session ends, it runs sosie scan in the background on everything the assistant keeps of the session: in Claude Code the transcript, its subagents’ transcripts and long tool results; in Copilot CLI the session’s folder. VS Code has no session end: it scans after each turn, one scan at a time. If a real value reached the session, the next session to start tells you the file, the line and the field, once, and the agent is told not to open them. A scan that fails is reported too, and keeps what earlier scans of the session found.

Cursor and Codex load the MCP server and the skill, but run no hooks from a plugin in this format: their transcripts are for sosie scan by hand.

The plugin starts no Sosie and holds no credentials. It runs @sosie/cli at its own version, the one released with it.

sosie scan

Proof, not trust: sosie scan searches files and folders for any real value that passed through Sosie.

npx @sosie/cli scan ~/.claude/projects
  ✗ /home/kim/.claude/projects/app/2026-11-02.jsonl:1203  a real value from format:email
  1 real value found in 412 files.

It never prints the real value: only the file’s full path, the line, and where the value came from: its field (users.api_key), or for a person’s value the format every field of it shares (format:email). It exits 1 when it finds one.

How it looks

  • Every text file under the paths given, skipping .git, node_modules and binary files. JSON string escapes are decoded, since transcripts are JSON lines.
  • Runs of words. Each line is split into words, and every run of one to four words is compared, by keyed hash, with the real values in the store. The store holds no plain values to compare against.
  • Only distinctive values: one to four words of at least four characters, and numbers of six digits or more. Years, ports and line numbers are not findings.
  • A fake is not a finding. It is what the agent was shown.
  • Fields that pass are not looked for, even with values faked before their rule, and neither are an API’s own words in its paths and query names, a JSON key that looks like a word (label), a value that is a name in the schema (Data, beside a column data), or one that a json document has for a key (LinkedIn, beside a key linkedin): a transcript holds those.

A common word held as text rather than an enum, a role admin or a status paid, is looked for like any other value, so a transcript that uses the word is a finding. Such a field belongs under pass in sosie.yml.

As a check

Its exit code makes it a check: a job that runs it fails when a real value reached a file.

sosie scan ./transcripts ./logs

scan compares with the store on the machine Sosie ran on, so it runs where the files and the store both are: the developer’s machine, or the host where Sosie runs for the team.

Edit this page on GitHub