Skip to main content
Glama
frinus-ai

Frinus MCP Server

by frinus-ai
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Frinus MCP Server

φρήν + νοῦς — The cognitive memory bridge between Claude agents and the Frinus platform.

MCP (Model Context Protocol) server that exposes 70 tools spanning cognitive memory, working memory, sessions, agents, the L0–L3 knowledge hierarchy, orchestration tasks, and training pipelines. The server speaks stdio and is consumed by Claude Desktop, Claude Code, and any MCP-aware client.

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.

Requirements

  • Node.js 18+

  • Frinus stack reachable (Memory Engine, Control Plane, Agent Service)

  • Personal API key (sk-frinus-...) tied to your tenant

Installation

npm install
npm run build

The build emits dist/index.js, ready to be wired into Claude Desktop / Claude Code.

Environment Variables

Variable

Default

Description

FRINUS_API_KEY

required

Personal API key (sk-frinus-...). Resolves tenant + user identity at boot.

MEMORY_SERVICE_URL

http://localhost:8001

Memory Engine base URL

FRINUS_CP_URL

http://localhost:8000

Control Plane base URL (universes, orgs, billing)

AGENT_SERVICE_URL

http://localhost:8002

Agent Service base URL (agents, invocation, skills)

FRINUS_MEMORY_API_KEY

—

Legacy fallback for FRINUS_API_KEY

Production endpoints (Frinus SaaS):

MEMORY_SERVICE_URL=https://frinus-memory.rdxsec.com.br
FRINUS_CP_URL=https://frinus-api.rdxsec.com.br
AGENT_SERVICE_URL=https://frinus-agents.rdxsec.com.br
FRINUS_API_KEY=sk-frinus-...

Claude Desktop / Claude Code Configuration

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "frinus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/index.js"],
      "env": {
        "FRINUS_API_KEY": "sk-frinus-...",
        "MEMORY_SERVICE_URL": "https://frinus-memory.rdxsec.com.br",
        "FRINUS_CP_URL": "https://frinus-api.rdxsec.com.br",
        "AGENT_SERVICE_URL": "https://frinus-agents.rdxsec.com.br"
      }
    }
  }
}

Claude Desktop config path: ~/.config/claude/claude_desktop_config.json (Linux) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). Claude Code config path: ~/.claude.json under mcpServers.

On startup the server validates the API key via /auth/me and resolves the tenant org ID + logged-in user. Failures abort the process with [FATAL] so the client surfaces the error.

The 7 Protocols

Protocol

When

Tools

Purpose

P1 — BOOT

Start of every session

session_start, working_memory_get, search_with_attention

Load identity + recent state + relevant context

P2 — CONSULT

Before any action

search_with_attention, session_context, memory_reinforce, memory_weaken

Retrieve, rate, and reinforce relevant memories

P3 — PLAN

Planning a task

memory_store(procedural), working_memory_add, stream_capture

Persist plans, working state, and architectural decisions

P4 — CAPTURE

Every 2–3 interactions

heartbeat_tick, working_memory_add, memory_store(episodic), stream_capture

Continuous recording of progress, bugs, patterns

P5 — LEARN

New knowledge

training_teach, training_qa, training_upload, training_stats, stream_process, sleep_run

Teach facts/procedures and run consolidation cycles

P6 — AUDIT

Maintenance

consolidation_detect_conflicts, consolidation_resolve_conflict, consolidation_detect_redundant, hierarchy_consolidate

Detect conflicts, redundancy, and consolidate memories

P7 — CLOSE

End of session

session_summary, stream_process, memory_store, hierarchy_consolidate, session_end

Summarise, promote stream items, persist learnings

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).

Tool

Description

memory_store

Create a memory. agent_id, content required. memory_type ∈ {episodic, semantic, procedural}. scope ∈ {user, agent, universe, organization}. importance 0–1.

memory_search

Semantic similarity search. Filters: agent_id, memory_types, limit.

memory_get

Fetch a memory by memory_id (full content, metadata, relevance).

memory_list

List memories for an agent_id with optional type filter.

memory_delete

Permanently delete a memory by memory_id.

memory_reinforce

Boost relevance of a useful memory (memory_id, boost 0–1, default 0.1).

memory_weaken

Penalise an outdated memory (memory_id, penalty 0–1, default 0.2).

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).

Tool

Description

working_memory_get

Load current state for a context. Always call at task start.

working_memory_add

Persist current state. Context formats: agent:{uuid}, universe:{uuid}, organization:{uuid}.

working_memory_clear

Remove all items for a context.

Sessions (5)

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

Tool

Description

session_start

Begin a session for an agent. Returns session_id. Supports parent_session_id for subagent inheritance.

session_end

Terminate a session and finalise its summary.

session_context

Combined working + long-term retrieval, enhanced with extracted session topics.

session_summary

Generate a structured recap (decisions, learnings, pending items).

session_clear

Wipe a session's working state without ending it.

Stream (4)

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

Tool

Description

stream_capture

Record an input / output / internal note tied to a session.

stream_get_session

Replay every captured item for a session_id.

stream_get_recent

Recent stream items across sessions (filterable).

stream_process

Promote pending items to long-term memory (manual trigger; scheduler also runs every 5 min).

Context & Attention (2)

Tool

Description

memory_get_context

Build a token-bounded context window for a task description.

search_with_attention

RAG with task-type-aware weighting. task_type ∈ {implementation, debug, deploy, documentation, review} drives memory_type weights.

Users (2)

Tool

Description

user_register

Register a user with the memory system (idempotent).

user_get_context

Retrieve combined user memories and tenant context.

Maintenance (2)

Tool

Description

heartbeat_tick

Cheap tick for an agent — drives relevance decay and lightweight consolidation.

sleep_run

Trigger a sleep cycle. phases ⊆ {evaluation, forgetting, consolidation, relevance}. Mirrors the scheduler's normal/deep sleeps.

Consolidation (3)

Tool

Description

consolidation_detect_conflicts

Surface candidate conflicting memories above a similarity threshold.

consolidation_resolve_conflict

Keep one memory, supersede the other with a written resolution note.

consolidation_detect_redundant

Find near-duplicates ready for merge or removal.

Memory Hierarchy (2)

Tool

Description

hierarchy_consolidate

Roll several related memories into a higher-level summary memory.

hierarchy_get_tree

Inspect the consolidation tree for a root memory.

Agents (6)

Agent CRUD + orchestrated invocation.

Tool

Description

agent_create

Create an agent (optionally from a template) scoped to a universe / team.

agent_list

List agents in the caller's tenant. Auto-scoped via API key.

agent_get

Fetch an agent by agent_id.

agent_update

Update persona, team, universe, etc.

agent_delete

Delete an agent.

agent_invoke

Programmatically invoke an agent with a task. Returns its tool calls and final answer. Used by delegation.

Universes (4)

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

Tool

Description

universe_create

Create a universe in the caller's org. Slug + name + description.

universe_list

List universes for the resolved org.

universe_update

Patch a universe (name, description).

universe_hierarchy

Walk the full L0 → L3 tree for a universe with status icons.

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.

Tool

Description

training_teach

Inject a fact or procedure. type ∈ {semantic, procedural}.

training_qa

Train with pairs of {question, answer}.

training_upload

Upload a document (file_path, filename) for chunked ingestion.

training_stats

Coverage statistics across the corpus.

training_gaps

Detected gaps in knowledge / weakly-covered topics.

training_recent

Most recently ingested memories from training.

Orchestration — Tasks (4)

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

Tool

Description

task_create

Create a task (title, description, optional assigned_agent_id, parent task).

task_get

Fetch a task with its full state.

task_list

List tasks with filters (status, agent, parent).

task_update

Update status, output, or assignment.

Skills (4)

Reusable behaviours assigned to agents.

Tool

Description

skill_list

Enumerate available skills in the tenant.

skill_assign

Attach a skill to an agent.

skill_remove

Detach a skill from an agent.

skill_agent_list

List the skills owned by a given agent.

Memory Types

Type

Use Case

Example

episodic

Record what happened

Bug: payment endpoint returned 500. Cause: missing null check on customer.address. Fix: guard + 422 response. File: services/payment.py

semantic

Store facts and knowledge

`MemoryResponse now includes universe_id (UUID

None) so the frontend can group memories per universe in the graph view.`

procedural

Document how-to procedures

Procedure: rotate-claude-credentials. Steps: 1) aws ecr login, 2) kubectl set image deployment/agent..., 3) verify pod is Ready. Caveat: deployment is named "agent", not "agent-service".

Scopes

Scope

Visibility

Use Case

user

Only the storing user

Personal preferences and history

agent

Only the storing agent

Agent-private notes

universe

All agents inside the universe (department)

Shared domain knowledge

organization

All agents in the tenant

Org-wide procedures and facts

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.

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.

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/frinus-ai/frinus-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server