Frinus MCP Server

φρήν + νοῦς — Gives your Claude agent long-term, cognitive memory backed by the Frinus platform.

frinus-mcp is an MCP (Model Context Protocol) server. It is the bridge between your MCP client — Claude Code, Cursor, or Claude Desktop — and the Frinus platform hosted at https://frinus.rdxsec.com.br.

It does not run on its own. It stores nothing locally: every tool call is forwarded over HTTPS to your Frinus account. So before it does anything useful you need two things:

1. a Frinus account (free, no card), and
2. a Frinus API key (sk-frinus-...).

With those in place, the server exposes 70 tools spanning cognitive memory, working memory, sessions, agents, the L0–L3 knowledge hierarchy, orchestration tasks, and training pipelines. It speaks stdio and works with any MCP-aware client.

• Version: 3.3.0
• Tools: 70 (see Tools Reference)
• Platform: https://frinus.rdxsec.com.br (hosted SaaS — the backend this server talks to)
• npm package: frinus-mcp

How it fits together

+-------------------+        +--------------+        +----------------------------+
| Your MCP client   | stdio  | frinus-mcp   | HTTPS  | Frinus platform            |
| (Claude Code,     | <----> | (this server,| <----> | frinus.rdxsec.com.br       |
|  Cursor, Desktop) |        |  via npx)    |        | (your memories live here)  |
+-------------------+        +--------------+        +----------------------------+

The server validates your API key against the platform at startup, resolves your account + organisation, and routes every tool call there. No API key → it refuses to start.

Rule Zero — MCP is mandatory

The Frinus MCP is the agent's long-term memory, identity, and intelligence. Without it the model is stateless across sessions. Every Claude agent that integrates with Frinus must:

1. Verify the MCP tools are reachable at conversation start (e.g. session_start, memory_search, search_with_attention).
2. If unreachable, surface the warning to the user: "MCP Frinus is not connected. Long-term memory capabilities are unavailable."
3. Execute the BOOT protocol (P1) before answering anything that is not a trivial greeting.
4. Persist learnings via memory_store before ending productive sessions.

The complete protocol set lives in the global CLAUDE.md (Frinus organisation), summarised below in The 7 Protocols.

Before you start — account + API key

You need a Frinus account and an API key. Both are free to get.

1. Create a free account

Sign up at https://frinus.rdxsec.com.br. The Free plan (R$0) is enough to get started:

• 100 memories
• 20 queries/day
• no credit card required

2. Generate an API key

Once logged in, open your account Settings → API Keys and create a new key. You'll get a value shaped like:

sk-frinus-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Copy it now — for security it's shown only once. This value goes into the FRINUS_API_KEY environment variable below. Treat it like a password; never commit it to a repo.

Environment Variables

In normal use you set only FRINUS_API_KEY. The service URLs already point at the hosted platform — leave them alone unless you self-host (see Advanced — self-host).

On startup the server validates the API key against the platform and resolves your organisation + logged-in user. If validation fails it aborts with [FATAL] so the client surfaces the error — re-check the key from Settings → API Keys.

The 7 Protocols

Detailed protocol scripts live in the agent's CLAUDE.md. Treat the table above as the contract every Frinus-integrated agent must respect.

Tools Reference

70 tools grouped by domain. Every tool returns text content; payloads follow the MCP Tool spec. Full JSON schemas live in src/tools/definitions.ts.

Memory (7)

Cognitive long-term memory: episodic (what happened), semantic (what I know), procedural (how to do things).

Working Memory (3)

Short-term, context-bound state. Miller's Law: max 7 items per context, oldest auto-evict. Default TTL 30 min (max 2 h).

Sessions (5)

Session = logical container for streams, working memory, and capture.

Stream (4)

Continuous capture pipeline. Items are batched, scored, and the important ones promoted to permanent memories.

Context & Attention (2)

Users (2)

Maintenance (2)

Consolidation (3)

Memory Hierarchy (2)

Agents (6)

Agent CRUD + orchestrated invocation.

Universes (4)

Universe = tenant-scoped knowledge domain. Holds the L0–L3 hierarchy.

Knowledge Hierarchy L0–L3 (16)

Universe
  └─ Concept   (L0)  body of knowledge
       └─ Theme  (L1)  thematic split
            └─ Topic   (L2)  unit of work (status: pending / in_progress / completed)
                 └─ Point   (L3)  atomic knowledge unit

Each level exposes create, list, update, delete:

• L0 Concepts: concept_create, concept_list, concept_update, concept_delete
• L1 Themes: theme_create, theme_list, theme_update, theme_delete
• L2 Topics: topic_create, topic_list, topic_update, topic_delete
• L3 Points: point_create, point_list, point_update, point_delete

topic_update and point_update accept a status field so agents can mark progress.

Training Pipeline (6)

Teach the system explicitly — facts, procedures, Q&A pairs, full documents.

Orchestration — Tasks (4)

Task table on the Memory Engine drives multi-agent orchestration.

Skills (4)

Reusable behaviours assigned to agents.

Credential Vault (5) — credential_exec broker

Encrypted credentials stored in the Control Plane, referenced from memories via credential_ref.

Secret-handling principle — server-side broker, never by value. The model never receives a secret value: no plaintext, no temp files, no shell snippets that carry the secret. To use a credential you call credential_exec. The MCP server (already running locally via npx -y frinus-mcp@latest) fetches the credential from the vault, injects its fields into the environment of a child process — never into argv, never into any text the model sees — runs the command with shell:false (no shell injection), and returns only the output.

// MYSQL_PWD / MYSQL_USER / MYSQL_HOST are pre-injected → standard clients just work
credential_exec(ref="mysql_prod", argv=["mysql", "-e", "SELECT 1"])
credential_exec(ref="pg_prod",    argv=["psql",  "-c", "SELECT 1"])

// For anything else, read the injected vars inside an explicit shell:
credential_exec(ref="jira_x", argv=["sh","-c",
  "curl -sS -H \"Authorization: Bearer $CRED_TOKEN\" \"$CRED_BASE_URL/whoami\""])

Injected env vars (when present in the credential): password/secret/token → MYSQL_PWD, PGPASSWORD, CRED_PASSWORD; user/username → CRED_USER, MYSQL_USER, PGUSER; host → CRED_HOST, MYSQL_HOST, PGHOST; port → CRED_PORT, MYSQL_TCP_PORT, PGPORT; database → CRED_DATABASE, PGDATABASE; any other scalar → CRED_<UPPER_SNAKE> (e.g. base_url → CRED_BASE_URL). argv must be an array of strings (no shell command string; use ["sh","-c","..."] if you really need a shell). 30s timeout, 256 KiB output cap. Everything ships in the npm package — the user installs nothing, edits no PATH, and runs no extra command; an up-to-date MCP is all that's required.

Memory Types

Scopes

The legacy agent / project / global scopes were retired together with project_id. Universes replaced projects as the isolation boundary inside an organisation.

Best Practices

Required formats for memories — make future retrieval deterministic:

• Bug: Bug: <description>. Cause: <root cause>. Fix: <solution>. File: <path>
• Pattern: Pattern: <description>. When to use: <context>. File: <path>
• Procedure: Procedure: <name>. Steps: 1) ... 2) ... 3) .... Caveats: <warnings>

Operational guidelines:

1. Always boot first. Call session_start + working_memory_get + search_with_attention before answering.
2. Reinforce / weaken on use. When a recalled memory helps, memory_reinforce. When it's wrong, memory_weaken (and replace it).
3. Capture every 2–3 turns. working_memory_add for state, stream_capture for decisions, memory_store for crystallised learnings.
4. Pick the right task_type. search_with_attention weights memory types per task. debug favours episodic, documentation favours semantic, deploy favours procedural.
5. Close the loop. End sessions with session_summary + stream_process + session_end. Run sleep_run for deeper consolidation when batches grow.
6. Audit before clutter accumulates. Periodic consolidation_detect_conflicts + consolidation_detect_redundant keep recall sharp.

Architecture

+---------------------+       +------------------+       +----------------------+
| Claude Agent /      | <---> | Frinus MCP       | <---> | Memory Engine        |
| Claude Code         | stdio | (this server)    | HTTPS | (memories, sessions, |
+---------------------+       +------------------+       |  hierarchy, tasks)   |
                                |                        +----------------------+
                                |                                  |
                                |                                  v
                                |                        +----------------------+
                                |                        | PostgreSQL+pgvector  |
                                |                        | + Apache AGE (graph) |
                                |                        +----------------------+
                                |
                                +---HTTPS---> Control Plane (universes, orgs)
                                +---HTTPS---> Agent Service (agents, invocation, skills)

• Memory Engine owns memories, working memory, sessions, streams, the L0–L3 hierarchy, training, sleep cycles, tasks, skills.
• Control Plane owns orgs, universes, members, API keys, billing, credentials, white-label, LLM keys.
• Agent Service owns agent runtime, tool dispatch, team routing, persona, invocation.

Tenant isolation is database-per-tenant. The MCP resolves your tenant org ID from the API key at boot — you never pass org_id manually.

Advanced — self-host / local dev

Everything above targets the hosted platform at https://frinus.rdxsec.com.br, which is what almost everyone wants. If you run your own Frinus stack (or develop the MCP against a local backend), build from source and override the three URLs:

git clone https://github.com/frinus-ai/frinus-mcp && cd frinus-mcp
npm install
npm run build      # emits dist/index.js

{
  "mcpServers": {
    "frinus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/index.js"],
      "env": {
        "FRINUS_API_KEY": "sk-frinus-...",
        "MEMORY_SERVICE_URL": "http://localhost:8001",
        "FRINUS_CP_URL": "http://localhost:8000",
        "AGENT_SERVICE_URL": "http://localhost:8002"
      }
    }
  }
}

Publishing (maintainers)

# 1) npm package — powers `npx -y frinus-mcp` everywhere
npm version <patch|minor|major>
npm publish                      # prepublishOnly runs the build

# 2) .mcpb bundle — powers the Claude Desktop one-click install
npm run pack:mcpb                # -> frinus.mcpb
gh release upload v<version> frinus.mcpb --repo frinus-ai/frinus-mcp --clobber
# Frontend points at: releases/latest/download/frinus.mcpb

Development

mcp/
  src/
    index.ts                       Entry: MCP server, dispatch, auth bootstrap
    client/
      memory-client.ts             HTTP client + identity state for Memory Engine
      cp-client.ts                 HTTP client for Control Plane
      agent-client.ts              HTTP client for Agent Service
    tools/
      definitions.ts               Tool schemas (70 tools)
      handlers.ts                  Tool handlers (70 handlers)
    capture/
      interaction-capture.ts       Auto stream capture for every tool call
    types/
      index.ts                     Shared types
  dist/                            Compiled output (npm run build)
  package.json
  tsconfig.json

Scripts:

npm run build     # tsc to dist/
npm run dev       # tsx hot reload (src/index.ts)
npm start         # node dist/index.js

Type checking: TypeScript 5.6+, ES modules, axios.

License

See repository root for license terms.

Getting started (zero to first memory)

Five minutes, four steps.

Step 1 — Create your account

Sign up at https://frinus.rdxsec.com.br (Free plan, no card). See above.

Step 2 — Generate your API key

Settings → API Keys → create. Copy the sk-frinus-... value. See above.

Step 3 — Add the server to your client

You don't install anything — npx fetches and runs the package on demand. The only value you must provide is your API key; the platform URLs already default to production.

Claude Code (one-liner):

claude mcp add frinus --env FRINUS_API_KEY=sk-frinus-... -- npx -y frinus-mcp@latest

Cursor / Claude Desktop / any client (config JSON):

{
  "mcpServers": {
    "frinus": {
      "command": "npx",
      "args": ["-y", "frinus-mcp@latest"],
      "env": {
        "FRINUS_API_KEY": "sk-frinus-..."
      }
    }
  }
}

Config file locations:

• Claude Code: ~/.claude.json, under mcpServers.
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / ~/.config/claude/claude_desktop_config.json (Linux). Or use the one-click .mcpb extension and just paste your API key.
• Cursor: ~/.cursor/mcp.json, under mcpServers.

Restart the client so it picks up the new server.

Replace sk-frinus-... with the real key from Step 2. You normally set only FRINUS_API_KEY — every backend URL already defaults to the hosted platform. See Environment Variables for the full list and the self-host override.

Step 4 — Validate with your first memory

In your client, ask the agent to store and recall something:

Store this in Frinus memory: "Our staging DB is reset every night at 02:00 UTC."

then in the same or a later session:

What time does our staging DB reset?

Behind the scenes the agent calls memory_store then memory_search / search_with_attention. If the recall comes back, the bridge is live. You can confirm the same memory appears in the web app at https://frinus.rdxsec.com.br.