MCP-1D: Implement the FastMCP server and transport startup

[Atharva-Kanherkar]

MCP-1D: Implement the FastMCP server and transport startup

Summary

Add the actual MCP server package and startup path, keeping it thin so it only validates parameters, calls core services, and formats responses.

Scope

• FastMCP server implementation
• tool registration for the chosen MCP surface
• one startup path that selects stdio or streamable-http
• startup validation and health exposure

Acceptance Criteria

• local clients can run the server over stdio
• remote/self-hosted clients can connect over /mcp via streamable HTTP
• transport is selected through one CLI/env-controlled startup path
• the MCP layer contains parameter validation and formatting only, not business logic

Dependencies

• Parent: MCP-1: Add an MCP server layer for agentic-memory #55
• Depends on: MCP-1A: Extract a shared runtime factory and remove global config mutation #58, MCP-1C: Define MCP tool schemas, routing, and bounded response contracts #60
• Blocks: MCP-1F: Package the server and document setup, ops, and migration guidance #63

[Atharva-Kanherkar]

@claude can you educate me using mermaid diagrams, and then explain each concepts to me, what has been made, and what needs to be made. what importantt decsiisons that need to be taken, and what concepts i will learn (python, system design, mcp) and then, explain everything to me in a very concise way

[claude]

Claude finished @Atharva-Kanherkar's task in 2m 45s —— View job

---

MCP-1D: Educational Deep-Dive

• Gathered repository context
• Analyzed built components (MCP-1A: Extract a shared runtime factory and remove global config mutation #58, MCP-1C: Define MCP tool schemas, routing, and bounded response contracts #60)
• Created diagrams and explanations

---

The Big Picture: What Is This Project?

This is an agentic memory system — a server that gives AI agents (like Claude) a brain with long-term memory. Think of it like building the hippocampus for an AI.

graph TD
    AI["🤖 AI Agent (Claude, GPT, etc.)"]
    MCP["MCP Server (this project)"]
    STORES["Memory Stores (ChromaDB)"]
    
    AI -->|"remember this fact"| MCP
    AI -->|"what do I know about X?"| MCP
    MCP -->|"store / retrieve / forget"| STORES
    STORES -->|"results"| MCP
    MCP -->|"here's what you know"| AI

Loading

---

System Architecture: The Full Stack

graph TB
    subgraph CLIENTS["Clients"]
        LOCAL["Local Claude\n(stdio)"]
        REMOTE["Remote Client\n(HTTP)"]
        WEB["Web UI\n(Next.js)"]
    end

    subgraph TRANSPORT["MCP-1D: Transport Layer (TO BUILD)"]
        STDIO["stdio transport"]
        HTTP["streamable-http /mcp"]
        FASTMCP["FastMCP server.py"]
        STDIO --> FASTMCP
        HTTP --> FASTMCP
    end

    subgraph API["MCP-1B: FastAPI REST (BUILT ✅)"]
        FASTAPI["api/app.py"]
    end

    subgraph SCHEMAS["MCP-1C: Contracts (BUILT ✅)"]
        SCH["mcp_server/schemas.py\nPydantic models"]
    end

    subgraph CORE["Core Services (BUILT ✅)"]
        RT["runtime.py\nbuild_runtime()"]
        SEM["SemanticStore\n(facts/knowledge)"]
        EPI["EpisodicStore\n(events/sessions)"]
        PRO["ProceduralStore\n(how-to skills)"]
        RET["UnifiedRetriever\n(ranked search)"]
        FORGET["ForgettingService\n(decay/prune)"]
        EMBED["GeminiEmbedder\n(768-dim vectors)"]
    end

    LOCAL --> STDIO
    REMOTE --> HTTP
    WEB --> FASTAPI

    FASTMCP --> SCH
    FASTMCP --> RT
    FASTAPI --> SCH
    FASTAPI --> RT

    RT --> SEM & EPI & PRO & RET & FORGET & EMBED
    SEM & EPI & PRO -->|ChromaDB| DB[("🗄️ chroma_db/")]

Loading

---

What Has Already Been Built

timeline
    title Build Progress
    section MCP-1A (DONE)
        Memory Models : MemoryRecord base class
                      : SemanticMemory (facts)
                      : EpisodicMemory (events)
                      : ProceduralMemory (skills)
    section MCP-1B (DONE)
        FastAPI Server : api/app.py REST endpoints
                      : CORS, file uploads, health
                      : Used by Web UI
    section MCP-1C (DONE)
        MCP Schemas : mcp_server/schemas.py
                    : All Pydantic request/response models
                    : Serialisation helpers
    section MCP-1D (THIS ISSUE)
        FastMCP Server : mcp_server/server.py
                      : Tool registration
                      : stdio + HTTP startup

Loading

Built (summary):

Component	File	What it does
Memory models	models/*.py	Typed dataclasses for 3 memory types
Storage	stores/*.py	ChromaDB-backed CRUD for each memory type
Retrieval	retrieval/retriever.py	Cross-store search with weighted ranking
Forgetting	forgetting/service.py	Time-decay, pruning, contradiction detection
Embeddings	utils/embeddings.py	Gemini multimodal vector embeddings
Runtime	runtime.py	Factory that wires everything together
REST API	api/app.py	FastAPI server for the Web UI
MCP Schemas	mcp_server/schemas.py	Pydantic contracts for all MCP tools

---

What Needs To Be Built (MCP-1D)

graph LR
    subgraph "mcp_server/server.py (TO CREATE)"
        A["1. Create FastMCP app\nmcp = FastMCP('agentic-memory')"]
        B["2. Register tools\n@mcp.tool() remember_fact\n@mcp.tool() recall_memories\netc."]
        C["3. Startup path\nif transport == 'stdio'\n  mcp.run()\nelse\n  uvicorn on /mcp"]
    end
    
    SCH["schemas.py (DONE)\nvalidation + serialisation"]
    RT["runtime.py (DONE)\nbusiness logic"]
    
    B -->|"calls"| SCH
    B -->|"calls"| RT

Loading

Concretely, you need to create mcp_server/server.py with:

1. FastMCP("agentic-memory") instance
2. One @mcp.tool() function per schema (10+ tools)
3. Each tool: validate input → call runtime → return serialised response
4. Startup: mcp.run(transport="stdio") or mcp.run(transport="streamable-http")

---

Concept 1: MCP (Model Context Protocol)

sequenceDiagram
    participant Claude
    participant MCPServer as MCP Server (you build this)
    participant ChromaDB

    Claude->>MCPServer: tool_call: remember_fact({content: "Paris is capital of France"})
    MCPServer->>ChromaDB: embed + store SemanticMemory
    ChromaDB-->>MCPServer: record_id
    MCPServer-->>Claude: {record: {...}, contradictions: [...]}

    Claude->>MCPServer: tool_call: recall_memories({query: "European capitals", top_k: 3})
    MCPServer->>ChromaDB: vector similarity search
    ChromaDB-->>MCPServer: ranked results
    MCPServer-->>Claude: {results: [{record, score}, ...]}

Loading

What MCP is: A standard protocol (like HTTP, but for AI tools) that lets any AI client call structured tools on your server. Claude natively speaks MCP — so once your server is up, Claude can use memory without any custom code.

Two transports:

• stdio — Claude Desktop runs your server as a subprocess, communicates via stdin/stdout. Zero network, ultra-low latency. For local dev.
• streamable-http — Your server runs as a web service at /mcp. Any remote client can connect. For deployed/self-hosted setups.

---

Concept 2: FastMCP (Python)

FastMCP is a Python library that makes building MCP servers trivial:

# What you'll write (simplified)
from fastmcp import FastMCP
from mcp_server.schemas import RememberFactRequest, serialise_remember_fact_response
from runtime import build_runtime

mcp = FastMCP("agentic-memory")
_rt = build_runtime()  # wires up all stores

@mcp.tool()
def remember_fact(content: str, importance: float = 0.5) -> dict:
    """Store a semantic memory (fact/knowledge)."""
    req = RememberFactRequest(content=content, importance=importance)
    # ... call _rt.semantic_store, run contradiction check
    # ... return serialised response

if __name__ == "__main__":
    mcp.run()  # defaults to stdio

Python concepts you'll use:

• @decorator — @mcp.tool() registers a function as an MCP tool
• dataclass — runtime.py uses @dataclass(slots=True) for zero-overhead structs
• async/await — FastMCP can run tools async for HTTP transport
• Pydantic — All schemas use Pydantic for auto-validation + serialisation
• TypeAdapter — Used for discriminated unions (the RecallEpisodesRequest pattern)

---

Concept 3: The Ranking Algorithm (System Design)

graph LR
    Q["Query: 'What do I know about Paris?'"]
    E["Embed query\n768-dim vector"]
    F["Over-fetch 3×\nfrom each store"]
    R["Rank by weighted score"]
    T["Top-K results"]

    Q --> E --> F --> R --> T

    subgraph "Weighted Score Formula"
        W["score = relevance × 0.4\n     + recency × 0.3\n     + importance × 0.3"]
    end
    R --> W

Loading

This is why the system retrieves 3× more results than needed — it casts a wide net, then ranks to find the best blend of recency + relevance + importance. This mirrors how human memory works (you remember both what's relevant AND what's recent/important).

---

Concept 4: Three Memory Types

graph TD
    subgraph SEMANTIC["Semantic Memory (facts)"]
        SF["'Paris is the capital of France'\ncategory, domain, confidence\ncontradiction-checked on write"]
    end
    subgraph EPISODIC["Episodic Memory (events)"]
        EF["'In session abc123, user asked about travel'\nsession_id, turn_number, participants\nemotional_profile, valence"]
    end
    subgraph PROCEDURAL["Procedural Memory (skills)"]
        PF["'Steps to book a flight: 1. go to... 2. select...'\nsteps[], preconditions[]\nwilson_score (success rate confidence)"]
    end
    
    SEMANTIC -->|"decays in 365 days"| FORGET["ForgettingService"]
    EPISODIC -->|"decays in 30 days"| FORGET
    PROCEDURAL -->|"decays in 180 days"| FORGET

Loading

---

Important Decisions to Make for MCP-1D

Decision	Options	Recommendation
Transport selection	env var MCP_TRANSPORT=stdio|http, or CLI arg --transport	Use env var — easier for Docker/Claude Desktop
Shared vs per-request runtime	Single _rt global vs lifespan context	Single global — ChromaDB connections are expensive
Async vs sync tools	async def or plain def	Sync is fine for stdio; async needed for HTTP concurrency
Health endpoint	Expose /health or MCP health resource	Add a health MCP resource (native to FastMCP)
fastmcp version	v1 vs v2 API	Use FastMCP v2 — cleaner, supports both transports

---

What You'll Learn

Area	Concept	Where used
Python	Decorators (@mcp.tool)	Tool registration
Python	Pydantic v2 models	All schemas
Python	Dataclasses with slots	MemoryRuntime
Python	Type aliases & discriminated unions	RecallEpisodesRequest
System Design	Transport abstraction	stdio vs HTTP startup
System Design	Weighted ranking / scoring	retrieval/ranking.py
System Design	Decay-based forgetting	forgetting/service.py
System Design	Event-driven observability	events/bus.py
MCP	Tool registration protocol	server.py
MCP	stdio transport	Local Claude Desktop
MCP	Streamable-HTTP transport	Self-hosted deployment
MCP	Request/response contracts	mcp_server/schemas.py

---

TL;DR: The core memory engine is fully built. MCP-1C built all the typed schemas. MCP-1D's job is the thin glue layer: create mcp_server/server.py that wraps the existing runtime in @mcp.tool() functions and adds a startup path that picks stdio vs HTTP. No business logic lives here — just parameter validation (already done by Pydantic schemas) and delegation to build_runtime().

[Atharva-Kanherkar]

@claude about procedural memory, can you please tell me if there is anything needed like tool calling, etc? i mean if i use it in claude code or codex, will it work perfectly? or there are any compatiabality issues

[claude]

Claude finished @Atharva-Kanherkar's task in 1m 25s —— View job

---

Procedural Memory: Compatibility with Claude Code & Codex

• Gathering context
• Reading procedural memory implementation
• Analyzing MCP tool compatibility
• Formulating response

---

Short answer

Claude Code → works perfectly once MCP-1D (server.py) is built.
Codex (GitHub Copilot) → not MCP-native, so there's a compatibility gap. Details below.

---

The Three Procedural Memory Tools

Once server.py is written (MCP-1D), the AI gets three tools for procedural memory:

Tool	What it does	Required fields
remember_procedure	Stores a how-to procedure	content, steps (≥1 step)
recall_procedures	Finds best procedures for a task	task, top_k
record_procedure_outcome	Marks a procedure as success/failure	record_id, success: bool

---

With Claude Code (✅ Works perfectly)

Claude Code natively speaks MCP. Once the server is running, Claude sees these tools in its context and calls them like any other MCP tool. The flow looks like this:

Claude Code
    │
    ├─ recall_procedures(task="deploy to production")
    │       └─ returns ranked procedures by combined_score
    │
    ├─ [executes the procedure steps]
    │
    └─ record_procedure_outcome(record_id="...", success=True)
            └─ updates wilson_score → better future ranking

One thing that needs to be in your system prompt: Claude must be instructed to call record_procedure_outcome after executing a procedure. This feedback loop is not automatic — if Claude forgets to close the loop, the wilson_score stays at 0.0 forever and ranking never improves beyond pure vector similarity.

---

With Codex / GitHub Copilot (⚠️ Not directly compatible)

Codex uses OpenAI function calling, not MCP. It cannot connect to an MCP server out of the box. Your options:

Option	How	Trade-off
Use the REST API	The FastAPI server (api/app.py) is already built — Codex can call /procedures endpoints via HTTP	No MCP magic, but works today
OpenAI-compatible adapter	Wrap server.py tools in an OpenAI-format tool schema	Extra work, not in scope for MCP-1D
MCP bridge (future)	Some tools can translate between OpenAI functions and MCP	Not standard yet

So for Codex, the answer is: use the FastAPI REST layer, not MCP. The same build_runtime() and stores back both, so the data is identical either way.

---

Compatibility Issue: steps is Required (Not Optional)

The single biggest gotcha for tool calling is this — in models/procedural.py:35:

_validate_string_list(self.steps, field_name="steps", allow_empty=False)

And in mcp_server/schemas.py:178:

steps: list[str] = Field(min_length=1)

The AI must provide at least one step when calling remember_procedure. If it tries to store a procedure with steps=[], the call fails with a validation error. This means:

• Your server.py tool docstring needs to make this crystal clear
• The AI calling the tool cannot treat steps as optional

---

The Wilson Score Feedback Loop

This is the most important system design point for procedural memory quality:

New procedure stored → wilson_score = 0.0
                       ranking = pure similarity

After outcomes:        wilson_score = lower bound of 95% CI
                       combined_score = 0.5 × similarity + 0.5 × wilson_score

From stores/procedural_store.py:186-196:

combined_score=(
    similarity                    # untested: only similarity
    if record.total_outcomes == 0
    else (
        similarity * 0.5 + record.wilson_score * 0.5   # tested: blended
    )
)

Why Wilson score and not just success rate? Wilson score is statistically conservative — a procedure with 1 success looks worse than one with 10 successes even at the same rate. This prevents newly-added procedures from ranking as if they're proven when they've only been tried once.

For Claude Code to get the benefit of this: the AI must be given explicit instructions in its system prompt to call record_procedure_outcome every time it runs a procedure. Without that instruction, the feedback loop never fires.

---

Summary of What Needs to Happen for Full Compatibility

1. Build mcp_server/server.py (MCP-1D) — register remember_procedure, recall_procedures, record_procedure_outcome as @mcp.tool() functions
2. Write a system prompt that tells Claude to close the feedback loop by calling record_procedure_outcome after executing any recalled procedure
3. For Codex: point it at the FastAPI REST API instead of MCP — no code changes needed, it already exposes the same runtime

[Atharva-Kanherkar]

@claude how will claude decide what to store, where to store, when to store and when not to?

[claude]

Claude finished @Atharva-Kanherkar's task in 1m 43s —— View job

---

How Claude Decides What/Where/When to Store Memory

• Gathered context
• Read memory models, schemas, contradiction detector, ranking algorithm
• Formulating answer

---

The Core Insight First

Claude does not make storage decisions autonomously. The decisions are split across three layers:

Layer	Who decides	Mechanism
What & When	Claude (LLM reasoning)	System prompt + tool docstrings
Where	Implicit in tool choice	Calling remember_fact vs remember_episode vs remember_procedure
Whether to keep	The server (automatic)	Contradiction detection + forgetting service

---

Decision 1: What to Store (Classification)

flowchart TD
    A["Claude encounters something noteworthy"] --> B{What kind of information?}
    
    B -->|"A fact, belief, or knowledge\n'Paris is the capital of France'\n'User prefers dark mode'"| C["remember_fact\n→ SemanticMemory"]
    
    B -->|"An event that happened\n'User asked me about travel in session xyz'\n'I made an error at turn 5'"| D["remember_episode\n→ EpisodicMemory"]
    
    B -->|"A step-by-step procedure\n'How to deploy this app:\n1. run tests 2. build 3. push'"| E["remember_procedure\n→ ProceduralMemory"]
    
    C --> F["ChromaDB: semantic collection"]
    D --> G["ChromaDB: episodic collection"]
    E --> H["ChromaDB: procedural collection"]

Loading

The critical mechanism: The @mcp.tool() docstrings in server.py (not yet built) are what Claude reads to make this classification. Claude cannot read your code — it only sees the tool description. So a well-written docstring like:

@mcp.tool()
def remember_fact(content: str, importance: float = 0.5, category: str = "general") -> dict:
    """Store a persistent fact or piece of knowledge.
    Use this for timeless truths, user preferences, domain knowledge,
    or beliefs. NOT for transient events or step-by-step procedures."""

...is literally the decision rule Claude uses.

---

Decision 2: Where to Store (Already Answered by "What")

graph LR
    FACT["remember_fact()"] -->|"schema: RememberFactRequest"| SS["SemanticStore\nChromaDB collection: 'semantic'"]
    EP["remember_episode()"] -->|"schema: RememberEpisodeRequest"| ES["EpisodicStore\nChromaDB collection: 'episodic'"]
    PROC["remember_procedure()"] -->|"schema: RememberProcedureRequest"| PS["ProceduralStore\nChromaDB collection: 'procedural'"]

Loading

"Where" is not a separate decision — it is a direct consequence of which tool Claude calls. The tool name IS the destination. There is no routing logic inside the server; each tool writes to exactly one store.

---

Decision 3: When to Store

sequenceDiagram
    participant User
    participant Claude
    participant MCP as MCP Server
    participant DB as ChromaDB

    User->>Claude: "Remember that I prefer TypeScript over JavaScript"
    Note over Claude: LLM decides: this is a user preference = fact
    Claude->>MCP: remember_fact({content: "User prefers TypeScript over JavaScript", importance: 0.8, category: "preferences"})
    MCP->>DB: embed + store
    DB-->>MCP: record_id
    MCP-->>Claude: {record: {...}, potential_contradictions: [...]}
    Note over Claude: Check if contradictions need resolving
    Claude-->>User: "Got it, I'll remember that."

Loading

"When" is driven entirely by the system prompt you give Claude. Without explicit instructions, Claude will never call these tools on its own. The system prompt must tell Claude:

• "After each user turn, consider if anything is worth storing"
• "Store user preferences immediately when stated"
• "After executing a procedure, call record_procedure_outcome"

---

Decision 4: When NOT to Store (The Automatic Safeguards)

This is where the server's logic kicks in automatically — Claude doesn't need to decide:

flowchart TD
    A["Claude calls remember_fact(...)"] --> B["Pydantic validation\nRememberFactRequest"]
    B -->|"Invalid: empty content,\nbad importance range, etc."| FAIL["❌ ValidationError\nTool call rejected"]
    B -->|"Valid"| C["Store in SemanticStore\n(embed + write to ChromaDB)"]
    C --> D["ContradictionDetector runs\nsimilarity threshold: 0.85"]
    D -->|"Similar existing memory found"| E["Returns potential_contradictions\nin response"]
    D -->|"No contradictions"| F["✅ Done, return record"]
    E --> G["Claude inspects contradictions\nMay call resolve_contradiction()"]
    
    style FAIL fill:#ff6b6b,color:#fff
    style F fill:#51cf66,color:#fff

Loading

Three automatic "when not to keep" mechanisms:

1. Validation Rejection — RememberFactRequest (schemas.py:141) rejects:

• Empty content (min_length=1)
• Invalid importance range
• Blank steps in procedures

2. Contradiction Detection — After storing a semantic fact, ContradictionDetector (forgetting/contradiction.py:27) runs a vector similarity search with threshold 0.85. If an existing memory is ≥85% similar, it's flagged. Claude then decides whether to call resolve_contradiction(), which sets superseded_by and drops importance to 0.0 on the old record.

3. Forgetting Service — Periodic run_forgetting_cycle() prunes automatically:

graph TD
    FS["ForgettingService.run_forgetting_cycle()"]
    FS --> SCAN["Scan all records across 3 stores"]
    SCAN --> SCORE["compute_decay_score(record)\n= time_decay × importance"]
    SCORE -->|"score > threshold"| KEEP["action: keep"]
    SCORE -->|"medium score"| FADE["action: fade\nimportance -= 0.1"]
    SCORE -->|"score < threshold OR\nsuperseded OR duplicate"| PRUNE["action: prune\ndelete from ChromaDB"]
    
    style KEEP fill:#51cf66,color:#fff
    style FADE fill:#ffd43b
    style PRUNE fill:#ff6b6b,color:#fff

Loading

Decay rates differ by memory type:

• Semantic: 365 days half-life
• Episodic: 30 days half-life
• Procedural: 180 days half-life

---

The importance Field: Claude's Hint to the Forgetting Service

When Claude calls remember_fact(content="...", importance=0.8), the importance value:

1. Goes into the ranking formula immediately: final_score = similarity×0.4 + recency×0.3 + importance×0.3 (ranking.py:65)
2. Governs how long it survives: low importance → decays faster → pruned sooner

So Claude indirectly controls retention lifetime by setting importance at write time. The system prompt should guide Claude to set higher importance for durable facts and lower for transient ones.

---

Complete Decision Flow Summary

flowchart LR
    subgraph CLAUDE["Claude (LLM Layer)"]
        SP["System Prompt\n(rules & triggers)"]
        TD["Tool Docstrings\n(what each tool is for)"]
        LLM["LLM Reasoning\n(classify + decide importance)"]
        SP --> LLM
        TD --> LLM
    end

    subgraph SERVER["MCP Server (Validation Layer)"]
        VAL["Pydantic Schemas\n(reject invalid calls)"]
        CONTRA["ContradictionDetector\n(flag near-duplicates)"]
    end

    subgraph INFRA["Storage Layer (Automatic)"]
        DB["ChromaDB\n(3 collections)"]
        FORGET["ForgettingService\n(decay + prune)"]
    end

    LLM -->|"tool call"| VAL
    VAL -->|"valid"| DB
    DB --> CONTRA
    FORGET -->|"periodic cycle"| DB

Loading

TL;DR: Claude classifies and timestamps; the tool docstrings are the classification rules; Pydantic rejects garbage input; contradiction detection flags conflicts; the forgetting service handles long-term cleanup. None of the "when not to keep" logic requires Claude to do anything — it's all automatic after the initial store.

[Atharva-Kanherkar]

Implementation lock for #61 after re-reading the issue, Claude's issue-thread notes, and the current repo state.

Locked decisions for MCP-1D:

• Build one thin server module under that delegates into the existing runtime and schema layer.
• Register the already-locked v1 tool surface; do not add extra tools in this issue.
• Keep one shared runtime instance per server process, initialized lazily from env/runtime config, rather than rebuilding stores per tool call.
• Select transport from a single startup path with .
• Use as the default local transport.
• Expose streamable HTTP at for remote/self-hosted use.
• Keep the MCP layer free of business logic: validation, error mapping, runtime calls, and serialization only.
• Use short, trigger-oriented tool descriptions/docstrings so hosts choose the right tool without wasting context tokens.
• Return stable typed error payloads from tool failures instead of free-form strings.
• Startup should validate config early enough to fail loudly on bad transport or unusable paths.

I’m implementing against those constraints on branch .

[Atharva-Kanherkar]

Implementation lock for #61 after re-reading the issue, Claude's issue-thread notes, and the current repo state.

Locked decisions for MCP-1D:

• Build one thin FastMCP server module under mcp_server/ that delegates into the existing runtime and schema layer.
• Register the already-locked v1 tool surface; do not add extra tools in this issue.
• Keep one shared runtime instance per server process, initialized lazily from env/runtime config, rather than rebuilding stores per tool call.
• Select transport from a single startup path with MEMORY_MCP_TRANSPORT=stdio|streamable-http.
• Use stdio as the default local transport.
• Expose streamable HTTP at /mcp for remote/self-hosted use.
• Keep the MCP layer free of business logic: validation, error mapping, runtime calls, and serialization only.
• Use short, trigger-oriented tool descriptions/docstrings so hosts choose the right tool without wasting context tokens.
• Return stable typed error payloads from tool failures instead of free-form strings.
• Startup should validate config early enough to fail loudly on bad transport or unusable paths.

I’m implementing against those constraints on branch feat/mcp-1d-server.