Claude Code transcript: What is MCP Really?

Now I understand your confusion. Let me explain how MCP actually works, which is quite different from your initial mental model.

The Key Misconception

Your intuition that "the LLM only understands natural language" led you to expect special tokens or text markers. But MCP doesn't communicate directly with the LLM at all. Instead:

┌─────────────┐    JSON-RPC/stdio    ┌─────────────┐
│  MCP Server │ ◄─────────────────► │    Host     │ ◄───► LLM
│  (this code)│                      │(Claude Code)│
└─────────────┘                      └─────────────┘

The Host (like Claude Code, Claude Desktop, or any MCP-compatible client) acts as the intermediary: 1. It connects to MCP servers via JSON-RPC (over stdio, HTTP, etc.) 2. It queries MCP servers for their available tools, prompts, and resources 3. It presents those tools to the LLM in the LLM's native tool format 4. When the LLM calls a tool, the Host translates it to an MCP protocol call

Where the "Instructions to the LLM" Actually Live

The "instruction" to the LLM comes from Python docstrings and type hints. Look at this tool definition in src/dirsrv_mcp/tools/users.py:21-45:

@mcp.tool()
def list_all_users(limit: int = 50, server_name: Optional[str] = None) -> Dict[str, Any]:
    """List users in the directory with computed status.

    Note: In privacy mode (default), returns count only.
    Set LDAP_MCP_EXPOSE_SENSITIVE_DATA=true for full user details.
    """

The @mcp.tool() decorator (from FastMCP) does several things: 1. Function name → becomes the tool name (list_all_users) 2. Docstring → becomes the tool description shown to the LLM 3. Type hints (limit: int, server_name: Optional[str]) → become the JSON schema for parameters 4. Return type → informs the expected response structure

Another example from src/dirsrv_mcp/tools/health.py:307-329:

@mcp.tool()
def first_look() -> Dict[str, Any]:
    """Comprehensive health overview - the go-to tool for "what's wrong with my directory?"

    Performs a complete health assessment across all configured servers including:
    - Server connectivity and basic health
    - Connection and thread utilization
    - Replication status and errors
    - Cache efficiency (entry cache hit ratios)
    - Disk space usage (local servers only)
    - SSL certificate expiration (local servers only)
    ...
    """

The Registration Pattern

In src/dirsrv_mcp/server.py:82-84, tools get registered:

self._register_prompts()
self._register_tools()
self._register_resources()

And _register_tools() calls functions like register_user_tools(mcp) which then use the @mcp.tool() decorator on each function.

The Protocol Layer (The "Missing" Code)

The protocol handling you're looking for is not in this project - it's in the fastmcp library. This project extends FastMCP:

from fastmcp import FastMCP

class LDAPAssistantMCP(FastMCP):
    ...

FastMCP handles: - JSON-RPC message serialization/deserialization - The tools/list, tools/call protocol methods - Schema generation from Python type hints - Transport (stdio, SSE, etc.)

The Actual Wire Protocol

When the Host asks "what tools do you have?", FastMCP responds with JSON like:

{
  "tools": [
    {
      "name": "list_all_users",
      "description": "List users in the directory with computed status...",
      "inputSchema": {
        "type": "object",
        "properties": {
          "limit": {"type": "integer", "default": 50},
          "server_name": {"type": "string"}
        }
      }
    }
  ]
}

When the LLM (via the Host) calls a tool:

{"method": "tools/call", "params": {"name": "list_all_users", "arguments": {"limit": 10}}}

FastMCP routes this to the decorated Python function and returns the result.

Summary

The "meat" you were looking for is: 1. Tool definitions: The @mcp.tool() decorated functions in src/dirsrv_mcp/tools/*.py 2. Protocol handling: The fastmcp library (not in this repo) 3. LLM instructions: Python docstrings that FastMCP extracts and serves via JSON-RPC

Excellent question - you're probing at something fundamental. Your intuition is correct: it's tokens all the way down.

The Reality: Tools Are Just Structured Text

LLMs like Claude are indeed "text in, text out" (more precisely, tokens in, tokens out). There is no separate "tool mechanism" at the neural network level. What we call "tools" is really:

1. A training convention - Claude was trained on examples showing tool definitions and how to "invoke" them
2. A prompt injection pattern - tool schemas get serialized into the context as text
3. An output parsing convention - certain output patterns are intercepted and interpreted as "tool calls"

What Actually Happens

When you (or Claude Code) make an API call with tools, something like this happens:

API Request (simplified):

{
  "messages": [{"role": "user", "content": "List LDAP users"}],
  "tools": [{
    "name": "list_all_users",
    "description": "List users in the directory...",
    "input_schema": {"type": "object", "properties": {"limit": {"type": "integer"}}}
  }]
}

What Claude Actually "Sees" (conceptually):

The API layer serializes this into the prompt context. While the exact format is proprietary, conceptually it's something like:

You have access to these tools:

<tool name="list_all_users">
<description>List users in the directory...</description>
<parameters>
  <param name="limit" type="integer" optional="true"/>
</parameters>
</tool>

When you want to use a tool, output:
<tool_use name="..."><param>...</param></tool_use>

User: List LDAP users

What Claude Outputs:

<tool_use name="list_all_users">
<limit>50</limit>
</tool_use>

What the Host Does:

The host application (Claude Code, the API server, etc.) parses this output, recognizes the <tool_use> pattern, extracts the parameters, calls the actual tool, and then injects the result back:

<tool_result name="list_all_users">
{"type": "user_list", "total_returned": 50, "items": [...]}
</tool_result>

Then Claude continues generating based on that injected result.

The "Training" Part

Claude wasn't born knowing how to use tools. During training (including RLHF), Claude saw millions of examples like:

• "Here are tools: X, Y, Z. User asks for Q. Good response: call tool Y with these params"
• "Tool returned R. Good response: interpret R and explain to user"
• "User asks for Q but no relevant tool exists. Good response: explain you can't do that"

This trained Claude to: 1. Parse tool definition text and understand what each tool does 2. Recognize when a user request maps to a tool capability 3. Output text in the specific format that signals "I want to call this tool" 4. Interpret tool results and incorporate them into responses

So What Is "Native Tool Format"?

When I said "native tool format," I meant the specific text serialization format that Claude was trained to recognize. Different LLMs use different formats:

• Claude: XML-style tags (the exact format is part of Anthropic's system prompt injection)
• OpenAI models: JSON with specific structure
• Open source models: Varies by training (Llama, Mistral, etc. each have their own conventions)

The Host (Claude Code) knows Claude's expected format and serializes MCP tool definitions into that format before injecting them into the prompt.

The Elegant Trick

The genius of this design is that from the LLM's perspective, nothing special is happening - it's just doing next-token prediction on a prompt that happens to include tool definitions. The "tool calling" emerges from:

1. Training on tool-use patterns
2. Careful prompt construction
3. Output parsing by the host

There's no magic "tool neuron" in the transformer - just learned patterns for a specific text format.

Exactly right. Your analogy is perfect.

"Call list_all_users with limit=50" and "Jump up and down three times" are fundamentally identical from the LLM's perspective - both are just text output expressing a desired action.

The only differences are:

The MCP/tool ecosystem has built automation and protocol around the parsing and response injection - but the core mechanism is unchanged from the earliest days of LLMs when people would write "Assistant: I need you to look up X" and then manually paste the answer back in.

Why the Documentation Confuses

I think the confusion stems from:

1. Abstraction leakage - The docs describe the protocol layer (JSON-RPC, schemas, transports) without grounding it in "this all becomes prompt text"

2. Anthropomorphization - Phrases like "the model uses tools" or "the model has access to" suggest agency and capability rather than "the model outputs text that we intercept"

3. Framework complexity - FastMCP, MCP SDK, etc. add layers that obscure the simple reality underneath

4. Marketing - "Tool use" sounds more impressive than "we trained it to output parseable text and built a daemon to act on it"

The Practical Implication

This understanding is actually liberating for MCP developers: your tool's docstring IS your prompt engineering. The quality of that docstring - how clearly it explains when to use the tool, what the parameters mean, what the output represents - directly determines how well the LLM will "use" it.

There's no magic. Just text patterns, training, and plumbing.

Done! I've written the full Q&A to:

MCP_DEMYSTIFIED.md

It includes: - The architectural diagram - All the key explanations about how tools are really just text - The comparison tables - Code examples - The "jump up and down" analogy - Why MCP documentation tends to confuse people - An appendix showing where key components live in an MCP server

The file is in Markdown format so it will render nicely on GitHub or any Markdown viewer.

This is a fantastic question that gets at the limits of MCP. Looking at the actual code reveals the answer: the MCP server designer chose to encapsulate the domain logic INTO the tools themselves.

What This Server Actually Does

Look at check_replication_lag() (lines 563-731). Instead of exposing a primitive "get RUV" tool, it:

1. Queries all agreements on the server
2. For each agreement, calls agmt.get_agmt_status() which internally compares supplier vs consumer CSNs
3. Returns pre-analyzed results: "In Synchronization", "lagging", "error"
4. Generates findings with severity levels

The LLM doesn't need to understand RUV comparison logic - the tool does it and returns:

if status.get("msg") == "In Synchronization":
    lag_entry["lag_status"] = "in_sync"
elif status.get("state") == "red":
    lag_entry["lag_status"] = "error"
else:
    lag_entry["lag_status"] = "lagging"

Similarly, get_replication_topology() (lines 403-561) queries all configured servers automatically and builds a comprehensive view.

The Three Strategies

Your question identifies a fundamental design tension. There are three approaches:

Strategy 1: Encode domain logic in the tool (what this server does)

User: "Are my servers caught up?"
         ↓
LLM sees: check_replication_lag() - "Analyze replication lag across agreements"
         ↓
LLM calls: check_replication_lag()
         ↓
Tool internally: queries all servers, compares CSNs, determines lag
         ↓
Returns: {"summary": "HEALTHY: All 3 agreements in sync", ...}

The LLM only needs to understand "this tool checks if replication is lagging" - not HOW to check.

Strategy 2: Rely on LLM's prior training knowledge

If you only had get_ruv(server), the LLM would need to: - Know to call it for each server - Know that RUVs contain CSNs - Know how to compare CSNs to detect lag

This works if and only if the LLM was trained on enough LDAP documentation. For 389 Directory Server? Probably yes - it's well-documented. For some obscure proprietary system? Probably not.

Strategy 3: Teach via prompts/docstrings

The server also registers prompts that guide orchestration. Let me show you:

Here's the third strategy in action. The diagnose_replication prompt (lines 178-202) teaches the LLM the orchestration workflow:

Step 1: Use get_replication_status for overview
Step 2: Use list_replication_conflicts to find conflicts
Step 3: Use check_replication_lag to identify sync delays
Step 4: Use get_agreement_status for deeper investigation

Your Core Insight Is Correct

You asked:

Perhaps it is relying on the LLM understanding the operation of LDAP servers from prior training data? If this is true then the MCP server isn't really adding fundamental capabilities to the LLM because it already understands LDAP servers.

This is partially true, and it's a profound observation:

An MCP server is like giving someone a calculator. The calculator adds computational capability, but if the person doesn't understand math, they won't know which buttons to press or what the output means.

The Practical Implications

For MCP server design:

1. Primitive tools require LLM domain knowledge - A get_ruv(server) tool only works if the LLM already understands LDAP replication

2. High-level tools encode your expertise - check_replication_lag() encapsulates the "compare CSNs across servers" logic so the LLM only needs to understand "check if lag exists"

3. Prompts can teach orchestration - If you must use primitives, prompts can guide multi-step workflows

4. Response design matters - Returning "in_sync" vs "lagging" is more LLM-friendly than raw CSN values

This MCP server chose well: it provides domain-aware tools that do the hard reasoning internally, so the LLM only needs to match user intent to tool purpose - not understand LDAP internals.

You've hit on something that I think is a genuine tension in the LLM tooling space, and your skepticism is warranted. Let me be direct about where the value is and isn't.

Where You're Right

For single-tool invocations by domain experts, the LLM layer is indeed mostly a "party trick":

Traditional CLI:
$ ldap-grokker check-replication-lag
{"summary": "HEALTHY: All 3 agreements in sync", ...}

LLM + MCP:
You: "check if my servers are lagging"
LLM: *calls check_replication_lag()*
     "Your servers are all in sync."

The second path adds: - Latency (API round-trip) - Cost (token usage) - Potential for error (LLM might misunderstand) - Dependency on external service

For you - someone who knows LDAP cold - the CLI is arguably better.

Where the LLM Might Add Value

The value proposition strengthens in specific scenarios:

1. Orchestration of multi-step investigations

You: "My LDAP server is slow, figure out why"

LLM: *calls get_performance_summary()*
     "Cache hit ratio is 45% - that's low. Let me check cache config..."
     *calls get_cache_statistics()*
     "Your entry cache is 200MB but you have 2M entries. Let me check memory..."
     *calls get_resource_utilization()*
     "You have 16GB free RAM. I recommend increasing nsslapd-cachememsize to 2GB.
      Here's the dsconf command: ..."

A CLI could do each step, but you'd need to know the diagnostic flow. The LLM chains tools based on intermediate results.

2. Interpretation in context

You: "Is this RUV lag concerning?"

LLM: "A lag of 3000 CSNs is moderate. Given your replication
      schedule of every 5 minutes and your ~100 writes/minute,
      this represents about 30 minutes of lag. That's unusual -
      normally you'd see <1 minute. Let me check the agreement status..."

The CLI gives you data; the LLM gives you meaning (if it's right).

3. Non-experts / unfamiliar domains

For someone who doesn't know LDAP: - They don't know check-replication-lag exists - They don't know what "RUV" or "CSN" means - They can't interpret the output

The LLM provides discoverability and translation.

4. Conversational refinement

You: "Check replication lag"
LLM: *shows results*
You: "Just for the dc=example,dc=com suffix"
LLM: *calls check_replication_lag(suffix="dc=example,dc=com")*
You: "Now compare to server2"
LLM: *remembers context, calls with server_name="server2"*

But Your Skepticism Is Valid

For domain experts doing routine tasks, the honest answer is:

The "maybe" entries depend heavily on the LLM actually getting it right, which isn't guaranteed.

The "Hidden App Store" Observation

Your framing of MCP as a "hidden app store" is astute. There's definitely an element of:

"Let's make utilities discoverable/invocable via natural language and call it AI"

The counter-argument would be: integration is valuable. Having 50 CLIs requires knowing 50 CLIs. Having 50 MCP servers behind one LLM interface means you can say "help me with X" and the right tool gets invoked.

But that's still largely a UX/discovery argument, not a "profound AI capability" argument.

My Honest Take

The LLM + MCP combination is most valuable when: 1. The user doesn't know what they don't know (exploration, not execution) 2. The task requires chaining multiple tools with reasoning between steps 3. Interpretation/explanation is needed, not just data 4. The domain is unfamiliar to the user

For an LDAP expert running routine checks? You might genuinely be better off with a CLI. The LLM layer adds friction without proportionate value.

The industry hype around "AI agents" sometimes obscures this reality. Not every hammer needs an LLM attached to it.

You're describing a plausible future, and it's worth examining seriously.

The Thesis

Instead of:

User → LLM → MCP protocol → MCP server → lib389 → LDAP server

Future:

User → LLM → generates Python using lib389 → executes it → LDAP server

The LLM already knows lib389 from training data. Why the indirection?

Arguments For Your Thesis

1. LLMs can already do this (sometimes)

Right now, I could write:

from lib389 import DirSrv
from lib389.replica import Replicas

ds = DirSrv()
ds.open(uri="ldap://server1:389", binddn="cn=admin", bindpw="...")
for replica in Replicas(ds).list():
    print(replica.get_ruv().format_ruv())

...and execute it. No MCP needed. The knowledge is in the training data.

2. MCP tools are just frozen code

The check_replication_lag() function in this MCP server is ~170 lines of Python. If the LLM can reliably generate equivalent code on demand, pre-packaging it adds no value.

3. Code generation is improving rapidly

As LLMs get better at: - Writing correct code first-try - Handling edge cases - Debugging their own errors

...the reliability gap between "call tested MCP tool" and "generate and run code" shrinks.

Arguments Against (Current Limitations)

1. Security and sandboxing

MCP tools are vetted, reviewed, have defined permissions. LLM-generated code might: - Have bugs - Accidentally delete data - Expose credentials - Do unexpected things

2. Credentials management

The MCP server handles auth configuration. If the LLM writes code, it needs credential access, which is a larger attack surface.

3. Reliability at the tail

LLM-generated code might work 95% of the time. For critical infrastructure (like LDAP servers), that 5% failure rate is unacceptable. Pre-tested tools have known behavior.

4. Efficiency

Generating, executing, and potentially debugging code is slower than calling a tested function.

But These Are Engineering Problems, Not Fundamental Barriers

With: - Better sandboxing (already exists in Claude Code) - Secure credential injection - Higher code generation reliability - Faster execution environments

...your vision becomes practical.

MCP as Transitional Technology?

Your implicit question is: Is MCP a transitional crutch that will be obsoleted?

Possibly yes. MCP might be the "training wheels" phase:

What Might Persist

Even in a "generate code directly" world, some value might remain in:

1. Trust/curation

For critical operations, you might still want human-vetted implementations. "Use the official lib389 MCP server" vs "let the LLM improvise."

2. Capabilities that aren't just code

Some tools provide access to things that aren't easily generated: - Proprietary APIs with complex auth flows - Hardware interfaces - Services requiring persistent connections/state

3. Efficiency for common operations

Generating code every time has overhead. Pre-built tools are faster for frequent operations.

4. The "app store" model

Even if unnecessary technically, vendors might prefer packaging capabilities as MCP servers for: - Branding - Monetization - Version control - Support boundaries

My Take

You've identified something real. MCP is partly a workaround for current LLM limitations: - Not reliable enough at code generation - Execution environments not secure enough - No standard way to provide credentials

As those limitations erode, the MCP abstraction may become unnecessary overhead for many use cases. The protocol layer is solving a problem that might not exist in 3-5 years.

The counterpoint is that "pre-packaged, tested, trusted capabilities" might always have value - even if technically unnecessary - for the same reasons we use libraries instead of writing everything from scratch.

Done. I've added three new sections to MCP_DEMYSTIFIED.md:

1. How Does the LLM Know Which Tool to Call? - The three strategies (encode logic in tools, rely on training, teach via prompts) with the LDAP replication example

2. What Value Does the LLM Actually Add? - Honest assessment of CLI vs LLM+MCP tradeoffs, acknowledging where your skepticism is valid

3. Is MCP a Transitional Technology? - Your thesis about future LLMs generating code directly, with arguments for and against

The document is now ~540 lines and covers the full arc of our conversation.