DEV Community: Ignacio Gonzalez Bohorquez

Following One Question Through the MCP Stack: 20 Steps from Prompt to Answer

Ignacio Gonzalez Bohorquez — Tue, 06 Oct 2026 08:09:40 +0000

Two Protocols, Three Translations: How a Host Bridges MCP and an LLM Provider API

Ignacio Gonzalez Bohorquez — Mon, 05 Oct 2026 17:43:25 +0000

Following one question through the MCP stack — from the user's prompt to the final answer

Modern AI applications increasingly sit between two different worlds: MCP (Model Context Protocol) and an LLM provider API.

MCP provides a standardized way for an AI application to discover and invoke external tools.

The LLM provider API provides the interface through which the application sends prompts, tool definitions, and tool results to the model.

The important part is that these two systems do not necessarily speak the same format.

The Host sits between them.

The Host discovers tools from an MCP Server, translates those tools into the format expected by the LLM provider, receives the LLM's tool decision, translates that decision back into an MCP request, executes the tool, and finally translates the result back into the provider's format so the LLM can produce a natural-language response.

This creates a useful mental model:

Two protocols. Three translations. One complete tool-call lifecycle.

In this article, we will follow one simple question through the entire process:

"What is 5 plus 7?"

Our MCP Server exposes one tool:

add_numbers(a: number, b: number) -> number

We will follow the request through 20 steps, divided into four phases:

Discovery — Steps 1–6
Translation and LLM Decision — Steps 7–10
Execution — Steps 11–16
Result and Response — Steps 17–20

1. The Architecture

Before looking at the 20 steps, we need to understand the components involved.

The architecture looks approximately like this:

                    ┌──────────────────┐
                    │       USER       │
                    │ "What is 5 + 7?" │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │       HOST       │
                    │                  │
                    │ Agent /          │
                    │ Orchestrator     │
                    └────────┬─────────┘
                             │
                        MCP / JSON-RPC
                             │
                             ▼
                    ┌──────────────────┐
                    │      CLIENT      │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │      SERVER      │
                    │                  │
                    │ Tool Registry    │
                    │                  │
                    │ add_numbers      │
                    └──────────────────┘


                    ┌──────────────────┐
                    │       HOST       │
                    └────────┬─────────┘
                             │
                       Provider API
                             │
                             ▼
                    ┌──────────────────┐
                    │       LLM        │
                    │                  │
                    │ Tool selection   │
                    │ Argument creation│
                    └──────────────────┘

The most important thing to understand is that there are two protocol boundaries.

The first is the MCP side.

The MCP Client and MCP Server communicate using MCP messages based on JSON-RPC.

For example:

{
  "method": "tools/list",
  "id": 1
}

Or:

{
  "method": "tools/call",
  "params": {
    "name": "add_numbers",
    "arguments": {
      "a": 5,
      "b": 7
    }
  },
  "id": 2
}

The second side is the LLM provider API.

The Host does not simply send those MCP JSON-RPC messages directly to the LLM.

Instead, the Host translates the MCP tool definition into the format expected by the provider.

For example, conceptually:

{
  "name": "add_numbers",
  "description": "Adds two numbers",
  "parameters": {
    "type": "object",
    "properties": {
      "a": {
        "type": "number"
      },
      "b": {
        "type": "number"
      }
    },
    "required": [
      "a",
      "b"
    ]
  }
}

The LLM can then respond with a provider-specific tool or function call such as:

{
  "function_call": {
    "name": "add_numbers",
    "arguments": "{\"a\":5,\"b\":7}"
  }
}

The Host then translates this back into an MCP tools/call request.

That is the bridge.

Phase 1 — Discovery

Steps 1–6

The first phase answers one fundamental question:

What tools are available?

At this point, the LLM has not yet been asked to solve the user's question.

The Host first needs to discover what tools are available from the MCP Server.

Step 1 — The User asks a question

The user enters:

What is 5 plus 7?

The Host receives this prompt.

At this moment, the Host knows what the user wants, but it may not yet know what tools are available on the connected MCP Server.

Step 2 — The Host starts discovery

The Host's orchestration layer starts the agent process.

Conceptually, we could imagine something like:

await agent.run("What is 5 plus 7?");

The Host now needs to discover the tools that are available.

It asks the MCP Client to perform tool discovery.

Step 3 — The Client sends tools/list

The MCP Client sends an MCP request to the Server.

Conceptually:

{
  "method": "tools/list",
  "id": 1
}

This is an MCP request using JSON-RPC.

The important point is that this message is part of the MCP communication between the Client and Server.

The LLM is not involved yet.

Step 4 — The Server reads its tool registry

The MCP Server receives the tools/list request.

The server maintains a tool registry.

Conceptually, the registry might contain:

{
  name: "add_numbers",
  description: "Adds two numbers",
  inputSchema: {
    ...
  },
  handler: ...
}

The registry contains both the public definition of the tool and the executable handler.

However, the Server does not send the implementation of the handler to the Client.

Instead, it exposes the public contract:

name
description
input schema

For example:

{
  "name": "add_numbers",
  "description": "Adds two numbers",
  "inputSchema": {
    "type": "object",
    "properties": {
      "a": {
        "type": "number"
      },
      "b": {
        "type": "number"
      }
    },
    "required": [
      "a",
      "b"
    ]
  }
}

The Server is effectively saying:

"I have a tool called add_numbers. It accepts two numbers: a and b."

Step 5 — The Server returns the tool list

The Server responds to the Client.

Conceptually:

{
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "add_numbers",
        "description": "Adds two numbers",
        "inputSchema": {
          "type": "object",
          "properties": {
            "a": {
              "type": "number"
            },
            "b": {
              "type": "number"
            }
          },
          "required": [
            "a",
            "b"
          ]
        }
      }
    ]
  }
}

Notice what was returned.

The Server returned:

name
description
schema

It did not return:

the implementation of the function

The handler remains on the Server.

Step 6 — The Client gives the tools to the Host

The MCP Client receives the response.

It passes the discovered tools back to the Host.

The Host now knows:

Tool:
    add_numbers

Arguments:
    a: number
    b: number

The discovery phase is complete.

The Host can now tell the LLM what tools are available.

Phase 2 — Translation and LLM Decision

Steps 7–10

This is where one of the most important architectural concepts appears.

The Host has an MCP tool definition.

But the LLM provider does not necessarily understand MCP's tool representation.

Therefore, the Host must perform a translation.

Step 7 — Translation #1

The Host converts the MCP tool schema into the tool/function schema expected by the LLM provider.

Conceptually:

MCP Tool Schema
       |
       | Translation #1
       v
LLM Provider Tool Schema

The MCP tool might look conceptually like:

{
  "name": "add_numbers",
  "description": "Adds two numbers",
  "inputSchema": {
    "type": "object",
    "properties": {
      "a": {
        "type": "number"
      },
      "b": {
        "type": "number"
      }
    },
    "required": [
      "a",
      "b"
    ]
  }
}

The Host transforms it into something the provider understands:

{
  "name": "add_numbers",
  "description": "Adds two numbers",
  "parameters": {
    "type": "object",
    "properties": {
      "a": {
        "type": "number"
      },
      "b": {
        "type": "number"
      }
    },
    "required": [
      "a",
      "b"
    ]
  }
}

The exact field names depend on the provider.

The important concept is the translation.

The Host is acting as an adapter between MCP and the provider API.

Step 8 — The Host sends the prompt and tools to the LLM

The Host now has two pieces of information:

User prompt:
"What is 5 plus 7?"

Available tool:
add_numbers

The Host sends both to the LLM provider.

Conceptually:

{
  "messages": [
    {
      "role": "user",
      "content": "What is 5 plus 7?"
    }
  ],
  "tools": [
    {
      "name": "add_numbers",
      "description": "Adds two numbers",
      "parameters": {
        "type": "object",
        "properties": {
          "a": {
            "type": "number"
          },
          "b": {
            "type": "number"
          }
        },
        "required": [
          "a",
          "b"
        ]
      }
    }
  ]
}

This is now a provider API request.

It is no longer the MCP tools/list request.

This distinction is critical.

The Host has crossed from:

MCP

into:

LLM Provider API

Step 9 — The LLM decides which tool to use

The LLM receives the user question and the available tool.

It reasons that the add_numbers tool is appropriate.

It generates the arguments:

{
  "a": 5,
  "b": 7
}

This is an important distinction.

The Server provided the schema.

The LLM generated the actual values.

The Server effectively said:

a must be a number
b must be a number

The LLM generates:

a = 5
b = 7

The model has therefore created new structured data that matches the schema it was given.

Step 10 — The LLM returns its tool decision

The provider returns something conceptually like:

{
  "function_call": {
    "name": "add_numbers",
    "arguments": "{\"a\":5,\"b\":7}"
  }
}

An extremely important point is that the LLM has not executed the function.

It has only requested that the Host execute it.

The LLM is effectively saying:

"I believe the add_numbers tool should be called with a = 5 and b = 7."

The Host is still responsible for the actual invocation.

Phase 3 — Execution

Steps 11–16

Now the Host has the LLM's tool decision.

But the decision is expressed in the provider's format.

The Host needs to turn it back into an MCP request.

Step 11 — Translation #2

The Host performs the second translation.

It takes the provider's tool call:

{
  "name": "add_numbers",
  "arguments": "{\"a\":5,\"b\":7}"
}

and converts it into an MCP tools/call request:

{
  "method": "tools/call",
  "params": {
    "name": "add_numbers",
    "arguments": {
      "a": 5,
      "b": 7
    }
  },
  "id": 2
}

The Host has now crossed the protocol boundary again:

LLM Provider API
       |
       | Translation #2
       v
MCP / JSON-RPC

Step 12 — The Client sends tools/call

The MCP Client sends the new request to the Server:

{
  "method": "tools/call",
  "params": {
    "name": "add_numbers",
    "arguments": {
      "a": 5,
      "b": 7
    }
  },
  "id": 2
}

Notice that this is a new JSON-RPC request.

The discovery request used:

id: 1

The tool invocation uses:

id: 2

The two requests are separate operations.

Step 13 — The Server looks up the tool

The Server receives the request.

It reads:

params.name

which contains:

add_numbers

The Server looks up that name in its registry.

Conceptually:

const tool = registry.get("add_numbers");

The Server now has access to the tool definition and its handler.

Step 14 — The Server validates the arguments

Before executing anything, the Server validates the arguments.

The arguments are:

{
  "a": 5,
  "b": 7
}

The Server validates them against the tool's schema.

Conceptually:

z.object({
  a: z.number(),
  b: z.number()
});

The validation succeeds:

a = 5    ✓ number

b = 7    ✓ number

This step is extremely important.

The LLM generated the arguments.

But the MCP Server should still validate them.

The model should not be treated as a trusted source of executable input.

The schema acts as a contract between the tool definition and the actual execution.

Step 15 — The Server executes the handler

Only now does the actual computation happen.

The Server executes:

5 + 7 = 12

The handler might look like:

async function addNumbers(args: {
  a: number;
  b: number;
}) {
  return args.a + args.b;
}

The Server then packages the result into an MCP-compatible result:

{
  "content": [
    {
      "type": "text",
      "text": "Result: 12"
    }
  ]
}

This is the first point in the lifecycle where the actual tool computation happens.

Everything before this point was discovery, translation, decision-making, validation, or orchestration.

Step 16 — The Server returns the result

The Server sends the result back to the Client:

{
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Result: 12"
      }
    ]
  }
}

This is again MCP/JSON-RPC.

The result has not yet been given back to the LLM.

The Client receives it first.

Phase 4 — Result and Response

Steps 17–20

The tool has now executed successfully.

The result is:

Result: 12

But the user did not ask to see raw tool output.

The user asked a natural-language question.

The Host therefore needs the LLM to turn the structured tool result into a final response.

Step 17 — The Client receives the result

The MCP Client receives:

Result: 12

and passes the result back to the Host.

The Host now has the output of the MCP tool.

Step 18 — Translation #3

The Host performs the third and final translation.

It converts:

MCP Tool Result

into:

LLM Provider Tool Result

Conceptually:

MCP Result
    |
    | Translation #3
    v
Provider Tool Output

For example:

{
  "role": "tool",
  "name": "add_numbers",
  "content": "Result: 12"
}

The exact structure depends on the LLM provider.

The important concept is that the Host again acts as the bridge.

Step 19 — The LLM generates the final answer

The LLM now receives the conversation context together with the tool result.

Conceptually:

User:

What is 5 plus 7?


Tool:

Result: 12

The LLM can now generate a natural-language response:

5 plus 7 is 12.

The tool provided the computation.

The LLM provides the conversational response.

Step 20 — The User sees the final answer

Finally, the Host returns:

5 plus 7 is 12.

The user sees:

5 plus 7 is 12.

The complete lifecycle is finished.

The Three Translations

The easiest way to understand the entire architecture is to focus on the three translations.

Translation #1

The Host converts:

MCP Tool Schema
        ↓
LLM Provider Tool Schema

This allows the LLM to understand which tools are available and what arguments they accept.

Translation #2

The Host converts:

LLM Provider Tool Call
        ↓
MCP tools/call

This takes the LLM's decision and turns it into an actual MCP tool invocation.

Translation #3

The Host converts:

MCP Tool Result
        ↓
LLM Provider Tool Result

This allows the LLM to see the result of the tool execution and formulate the final response.

The Complete Flow

We can now compress the entire architecture into one diagram:

USER
  |
  | "What is 5 + 7?"
  v
HOST
  |
  | Start discovery
  v
CLIENT
  |
  | tools/list
  v
SERVER
  |
  | Read tool registry
  | Return tool definitions
  v
CLIENT
  |
  v
HOST
  |
  | Translation #1
  | MCP schema -> Provider schema
  v
LLM
  |
  | Decide:
  | add_numbers(a=5,b=7)
  v
HOST
  |
  | Translation #2
  | Provider call -> MCP tools/call
  v
CLIENT
  |
  | tools/call
  v
SERVER
  |
  | Find tool
  | Validate arguments
  | Execute handler
  |
  | 5 + 7 = 12
  v
CLIENT
  |
  v
HOST
  |
  | Translation #3
  | MCP result -> Provider result
  v
LLM
  |
  | "5 plus 7 is 12."
  v
HOST
  |
  v
USER

The Complete 20-Step Lifecycle

Here is the entire process in one place.

Phase 1 — Discovery

1. User

The user asks:

"What is 5 plus 7?"

2. Host

The Host starts the agent and initiates tool discovery.

3. Client

The MCP Client sends:

{
  "method": "tools/list",
  "id": 1
}

4. Server

The MCP Server reads its tool registry and prepares the available tool definitions.

5. Server

The Server responds:

{
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "add_numbers",
        "description": "Adds two numbers",
        "inputSchema": {}
      }
    ]
  }
}

6. Client

The Client passes the tool definitions back to the Host.

Phase 2 — Translation and LLM Decision

7. Host — Translation #1

The Host converts:

MCP tool schema
        ↓
Provider tool schema

8. Host

The Host sends the user's prompt and the translated tools to the LLM provider.

9. LLM

The LLM determines that add_numbers is appropriate and generates:

{
  "a": 5,
  "b": 7
}

10. LLM

The LLM returns its provider-specific tool/function call.

Phase 3 — Execution

11. Host — Translation #2

The Host converts the provider tool call into an MCP tools/call.

12. Client

The Client sends:

{
  "method": "tools/call",
  "params": {
    "name": "add_numbers",
    "arguments": {
      "a": 5,
      "b": 7
    }
  },
  "id": 2
}

13. Server

The Server looks up add_numbers in its registry.

14. Server

The Server validates:

a = 5 ✓
b = 7 ✓

15. Server

The Server executes the handler:

5 + 7 = 12

16. Server

The Server returns the MCP result.

Phase 4 — Result and Response

17. Client

The Client receives the MCP result and passes it to the Host.

18. Host — Translation #3

The Host converts:

MCP result
    ↓
Provider tool result

and sends it to the LLM.

19. LLM

The LLM generates:

"5 plus 7 is 12."

20. User

The user sees:

5 plus 7 is 12.

TypeScript Example

The following simplified TypeScript code demonstrates the main architectural boundaries.

import { z } from "zod";

// ==========================================
// 1. TOOL DEFINITION
// ==========================================

const addNumbersSchema = z.object({
  a: z.number(),
  b: z.number(),
});

type AddNumbersArgs = z.infer<typeof addNumbersSchema>;

const tool = {
  name: "add_numbers",

  description: "Adds two numbers",

  inputSchema: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" },
    },
    required: ["a", "b"],
  },

  handler: async (args: AddNumbersArgs) => {
    return args.a + args.b;
  },
};


// ==========================================
// 2. MCP: tools/list
// ==========================================

function listTools() {
  return {
    tools: [
      {
        name: tool.name,
        description: tool.description,
        inputSchema: tool.inputSchema,
      },
    ],
  };
}


// ==========================================
// 3. TRANSLATION #1
//
// MCP schema
//      ↓
// Provider schema
// ==========================================

function toProviderTool(mcpTool: any) {
  return {
    name: mcpTool.name,
    description: mcpTool.description,
    parameters: mcpTool.inputSchema,
  };
}


// ==========================================
// 4. TRANSLATION #2
//
// Provider function call
//      ↓
// MCP tools/call
// ==========================================

function toMcpToolCall(functionCall: any) {
  return {
    method: "tools/call",

    params: {
      name: functionCall.name,

      arguments: JSON.parse(
        functionCall.arguments
      ),
    },

    id: 2,
  };
}


// ==========================================
// 5. SERVER EXECUTION
// ==========================================

async function executeTool(
  name: string,
  arguments_: unknown
) {

  if (name !== tool.name) {
    throw new Error(
      `Unknown tool: ${name}`
    );
  }

  // Server-side validation
  const args =
    addNumbersSchema.parse(arguments_);

  // Actual computation
  const result =
    await tool.handler(args);

  return {
    content: [
      {
        type: "text",
        text: `Result: ${result}`,
      },
    ],
  };
}


// ==========================================
// 6. TRANSLATION #3
//
// MCP result
//      ↓
// Provider tool result
// ==========================================

function toProviderToolResult(
  mcpResult: any
) {
  return {
    role: "tool",
    content: mcpResult.content,
  };
}

Python Example

The same architecture can be represented in Python.

from typing import Any
import json


# ==========================================
# 1. TOOL DEFINITION
# ==========================================

def add_numbers(a: float, b: float) -> float:
    return a + b


TOOL = {
    "name": "add_numbers",

    "description": "Adds two numbers",

    "inputSchema": {
        "type": "object",

        "properties": {
            "a": {
                "type": "number"
            },
            "b": {
                "type": "number"
            }
        },

        "required": [
            "a",
            "b"
        ]
    }
}


# ==========================================
# 2. MCP: tools/list
# ==========================================

def list_tools() -> dict:
    return {
        "tools": [
            {
                "name": TOOL["name"],
                "description": TOOL["description"],
                "inputSchema": TOOL["inputSchema"]
            }
        ]
    }


# ==========================================
# 3. TRANSLATION #1
#
# MCP schema
#      ↓
# Provider schema
# ==========================================

def to_provider_tool(
    mcp_tool: dict
) -> dict:

    return {
        "name": mcp_tool["name"],
        "description": mcp_tool["description"],
        "parameters": mcp_tool["inputSchema"]
    }


# ==========================================
# 4. TRANSLATION #2
#
# Provider function call
#      ↓
# MCP tools/call
# ==========================================

def to_mcp_call(
    function_call: dict
) -> dict:

    arguments = json.loads(
        function_call["arguments"]
    )

    return {
        "method": "tools/call",

        "params": {
            "name": function_call["name"],
            "arguments": arguments
        },

        "id": 2
    }


# ==========================================
# 5. SERVER EXECUTION
# ==========================================

def execute_tool(
    name: str,
    arguments: dict
) -> dict:

    if name != "add_numbers":
        raise ValueError(
            f"Unknown tool: {name}"
        )

    # Server-side validation

    if not isinstance(
        arguments.get("a"),
        (int, float)
    ):
        raise ValueError(
            "a must be a number"
        )

    if not isinstance(
        arguments.get("b"),
        (int, float)
    ):
        raise ValueError(
            "b must be a number"
        )

    # Actual computation

    result = add_numbers(
        arguments["a"],
        arguments["b"]
    )

    return {
        "content": [
            {
                "type": "text",
                "text": f"Result: {result}"
            }
        ]
    }


# ==========================================
# 6. TRANSLATION #3
#
# MCP result
#      ↓
# Provider tool result
# ==========================================

def to_provider_result(
    mcp_result: dict
) -> dict:

    return {
        "role": "tool",
        "content": mcp_result["content"]
    }

A Simplified End-to-End Host

We can combine the concepts into a simplified Host implementation.

async function runAgent(
  userPrompt: string
) {

  // ======================================
  // PHASE 1: DISCOVERY
  // ======================================

  const mcpResponse =
    await mcpClient.request({
      method: "tools/list",
      id: 1,
    });

  const mcpTools =
    mcpResponse.result.tools;


  // ======================================
  // TRANSLATION #1
  // ======================================

  const providerTools =
    mcpTools.map(
      toProviderTool
    );


  // ======================================
  // PHASE 2: ASK THE LLM
  // ======================================

  const llmResponse =
    await llmProvider.chat({

      messages: [
        {
          role: "user",
          content: userPrompt,
        },
      ],

      tools: providerTools,
    });


  // ======================================
  // LLM SELECTED A TOOL
  // ======================================

  const functionCall =
    llmResponse.function_call;


  // ======================================
  // TRANSLATION #2
  // ======================================

  const mcpCall =
    toMcpToolCall(
      functionCall
    );


  // ======================================
  // PHASE 3: EXECUTE THROUGH MCP
  // ======================================

  const toolResult =
    await mcpClient.request(
      mcpCall
    );


  // ======================================
  // TRANSLATION #3
  // ======================================

  const providerResult =
    toProviderToolResult(
      toolResult
    );


  // ======================================
  // FINAL LLM RESPONSE
  // ======================================

  const finalResponse =
    await llmProvider.chat({

      messages: [

        {
          role: "user",
          content: userPrompt,
        },

        {
          role: "tool",
          content:
            providerResult.content,
        },

      ],
    });


  return finalResponse;
}

Why This Architecture Matters

Understanding this flow changes how we think about MCP.

MCP is not simply:

"A way for an LLM to call a function."

Instead, MCP provides a standardized interface through which an AI application can discover and invoke tools.

The Host connects that standardized interface to an LLM provider.

This creates a separation of responsibilities.

The MCP Server does not need to know which LLM is being used.

The LLM does not need to know how the MCP Server internally implements its tools.

The Host coordinates everything.

The architecture can therefore look like:

                  ┌─────────────────┐
                  │   MCP SERVER    │
                  │                 │
                  │  add_numbers    │
                  │  search         │
                  │  database       │
                  │  APIs           │
                  └────────┬────────┘
                           │
                          MCP
                           │
                           ▼
                  ┌─────────────────┐
                  │      HOST       │
                  │                 │
                  │  Discovery      │
                  │  Translation    │
                  │  Orchestration  │
                  └────────┬────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
            LLM A        LLM B        LLM C

The MCP Server exposes tools.

The Host translates and orchestrates.

The LLM decides which tool to use.

The Server validates and executes.

The LLM finally turns the result into natural language.

MCP Is Not the LLM Provider API

This is probably the most important takeaway from this entire flow.

It is tempting to think about the architecture like this:

User
  ↓
MCP
  ↓
LLM

But a more accurate representation is:

                    ┌─────────────┐
                    │    USER     │
                    └──────┬──────┘
                           │
                           ▼
                    ┌─────────────┐
                    │    HOST     │
                    └──────┬──────┘
                           │
             ┌─────────────┴─────────────┐
             │                           │
             ▼                           ▼
        MCP Protocol              Provider API
             │                           │
             ▼                           ▼
          CLIENT                        LLM
             │
             ▼
          SERVER
             │
             ▼
           TOOLS

The Host is therefore an adapter and orchestrator between the two protocol worlds.

The MCP Server Does Not Tell the LLM What to Do

Another important distinction is responsibility.

The MCP Server says:

"Here is a tool I expose, its description, and the arguments it accepts."

The LLM decides:

"This tool is appropriate for the user's question, and I want to call it with these arguments."

The Host coordinates the process.

The Server validates and executes.

This can be summarized as:

Component	Responsibility
User	Provides intent
Host	Orchestrates the lifecycle
MCP Client	Communicates with MCP Servers
MCP Server	Exposes and executes tools
Tool Registry	Stores tool definitions and handlers
LLM	Decides whether and how to use a tool
Schema	Defines valid arguments
Tool Handler	Performs the actual operation

The Most Important Security Boundary

One of the most important details in this architecture is validation.

The LLM generates:

{
  "a": 5,
  "b": 7
}

But the Server should not simply assume those arguments are valid.

The Server validates them against its own schema.

For example:

const schema = z.object({
  a: z.number(),
  b: z.number(),
});

const validatedArgs =
  schema.parse(arguments);

This creates an important boundary:

LLM-generated data
        |
        v
Server validation
        |
        | valid
        v
Tool execution

The LLM is probabilistic.

The tool execution environment should remain deterministic and controlled.

The schema therefore becomes an important contract between model-generated arguments and real-world execution.

The Final Mental Model

If there is only one diagram to remember from this entire article, it should be this:

USER
  │
  │ "What is 5 + 7?"
  ▼
HOST
  │
  │ MCP discovery
  ▼
CLIENT
  │
  │ tools/list
  ▼
SERVER
  │
  │ Tool registry
  │ Tool definitions
  ▼
CLIENT
  │
  ▼
HOST
  │
  │ Translation #1
  │
  │ MCP schema
  │       ↓
  │ Provider schema
  ▼
LLM
  │
  │ Tool decision
  │ add_numbers
  │ a = 5
  │ b = 7
  ▼
HOST
  │
  │ Translation #2
  │
  │ Provider tool call
  │       ↓
  │ MCP tools/call
  ▼
CLIENT
  │
  │ tools/call
  ▼
SERVER
  │
  │ Find tool
  │ Validate arguments
  │ Execute handler
  │
  │ 5 + 7 = 12
  ▼
CLIENT
  │
  ▼
HOST
  │
  │ Translation #3
  │
  │ MCP result
  │       ↓
  │ Provider tool result
  ▼
LLM
  │
  │ "5 plus 7 is 12."
  ▼
HOST
  │
  ▼
USER

The entire lifecycle can therefore be summarized in one sentence:

Discover → Translate → Decide → Translate → Execute → Translate → Respond.

Or, even more simply:

The Host is the bridge between MCP and the LLM provider.

MCP standardizes how the Host discovers and invokes tools.

The LLM provider API defines how the Host communicates with the model.

The Host connects these two worlds through three translations:

1. MCP Tool Schema
        ↓
   Provider Tool Schema

2. Provider Tool Call
        ↓
   MCP tools/call

3. MCP Tool Result
        ↓
   Provider Tool Result

And that is the real story behind a seemingly simple question such as:

"What is 5 plus 7?"

Behind that one sentence is an entire lifecycle of discovery, protocol messages, schema translation, model decision-making, argument generation, validation, tool execution, result translation, and final natural-language generation.

That is the MCP tool-call lifecycle.

Two protocols. Three translations. One complete request.

MCP-USE Explained: Building Full-Stack AI Agents and MCP Apps with TypeScript and Python

Ignacio Gonzalez Bohorquez — Tue, 29 Sep 2026 09:40:29 +0000

The Model Context Protocol (MCP) has quickly become an important building block for connecting AI applications with external tools, data, APIs, and services.

At its core, MCP provides a standardized protocol through which AI applications can discover and interact with capabilities exposed by MCP servers.

But there is an important distinction between implementing MCP and building an application around MCP.

Writing an MCP server is only one part of the problem.

A production-grade AI application may also need:

MCP clients
LLM integration
Agent orchestration
Tool discovery and execution
Authentication
Multiple MCP servers
Structured outputs
Observability and debugging
Interactive user interfaces
Deployment and testing

This is where mcp-use becomes interesting.

mcp-use is an open-source framework designed to make it easier to build applications around MCP, including MCP clients, agents, servers, and, in its TypeScript ecosystem, interactive MCP Apps.

This article explores the architecture, the problems mcp-use solves, and how to use it to build MCP-powered AI applications.

What Problem Does MCP Solve?
MCP Is Not an Agent Framework
What Is mcp-use?
The Dual Nature of mcp-use
MCP Tools: The Bridge Between LLMs and Real Systems
Type Safety With Schemas
mcp-use and Agents
Connecting Multiple MCP Servers
MCP Resources vs Tools
Interactive MCP Apps
Why UI + MCP Is Interesting
The mcp-use Inspector
Testing MCP Servers From the CLI
Authentication
Structured Output
Integrating With Existing Agent Frameworks
Python vs TypeScript
A Simple End-to-End Architecture
What mcp-use Actually Adds

1. What Problem Does MCP Solve?

Before understanding mcp-use, it is important to understand MCP itself.

An LLM can generate text, but by itself it does not automatically have access to your database, Git repository, internal APIs, filesystem, browser, or business applications.

Traditionally, every AI application had to implement its own integration mechanism.

For example:

LLM
 |
 +-- Custom weather API integration
 |
 +-- Custom database integration
 |
 +-- Custom GitHub integration
 |
 +-- Custom filesystem integration
 |
 +-- Custom browser integration

As the number of integrations grows, this becomes increasingly difficult to maintain.

MCP introduces a standardized interface between AI applications and external capabilities.

Conceptually:

                 MCP
                  |
        +---------+---------+
        |                   |
     Client              Server
        |                   |
       LLM          Tools / Resources
                            |
                    External systems

An MCP server can expose capabilities such as:

Tools
 ├── search_database()
 ├── create_ticket()
 └── deploy_application()

Resources
 ├── database://customers
 └── file://documentation

Prompts
 ├── analyze_customer()
 └── generate_report()

The AI application can then discover and use these capabilities through MCP.

The key idea is that MCP standardizes the communication between AI applications and external capabilities.

2. MCP Is Not an Agent Framework

This distinction is extremely important.

MCP defines how applications communicate with tools and contextual capabilities.

It does not require you to use a particular LLM or agent framework.

Think of MCP as a standardized communication layer:

                  AI Application
                       |
                +------+------+
                |             |
              Agent          LLM
                |
             MCP Client
                |
          Model Context Protocol
                |
             MCP Server
                |
        +-------+-------+
        |       |       |
      API      DB     Files

Each layer has a different responsibility.

LLM

The LLM performs reasoning and generates responses.

Agent

The agent orchestrates the workflow and determines what should happen next.

MCP Client

The MCP client connects the application or agent to MCP servers.

MCP

MCP defines the standardized communication protocol.

MCP Server

The server exposes capabilities such as tools, resources, and prompts.

External Systems

These are the actual systems being accessed:

Databases
APIs
GitHub
Cloud platforms
Files
SaaS applications
Enterprise systems

Therefore:

MCP is a protocol, not an agent framework.

This distinction becomes extremely important when designing AI architectures.

3. What Is mcp-use?

mcp-use provides higher-level tooling for building applications on top of MCP.

The current ecosystem includes both Python and TypeScript implementations.

The TypeScript framework provides a broader full-stack development experience including:

MCP servers
MCP clients
Agents
Typed tools
Interactive Views
MCP Apps
Inspector
CLI tooling

The Python ecosystem focuses heavily on connecting LLMs and agents to MCP servers.

At a conceptual level:

                 Your AI Application
                         |
              +----------+----------+
              |                     |
             LLM                  Agent
              |                     |
              +----------+----------+
                         |
                      mcp-use
                         |
                 +-------+-------+
                 |               |
             MCP Client      MCP Server
                 |               |
                 +-------+-------+
                         |
                 External systems

The important idea is that mcp-use provides abstractions around the MCP ecosystem, instead of requiring developers to implement every layer manually.

4. The Dual Nature of mcp-use

One of the interesting aspects of mcp-use is that it is not limited to one side of the MCP connection.

It can be understood as supporting two major directions.

Server Side

You can build MCP servers that expose:

Tools
Data
Resources
UI capabilities

Client / Agent Side

You can build applications that:

Connect to MCP servers
Discover tools
Invoke tools
Read resources
Use prompts
Give those capabilities to an LLM or agent

Conceptually:

                    mcp-use
                       |
          +------------+------------+
          |                         |
       Server                    Client
          |                         |
      Exposes                   Consumes
          |                         |
     Tools / Data               Tools / Data
          |                         |
          +----------- MCP ---------+

This is an important architectural distinction.

You are not simply building:

"an MCP server."

You can build an entire application ecosystem around MCP.

5. MCP Tools: The Bridge Between LLMs and Real Systems

One of the fundamental MCP concepts is the tool.

A tool gives a model the ability to request an operation.

For example:

def add_numbers(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

The important concept is not simply the function itself.

The important part is that the function has a machine-readable identity and schema.

A tool can conceptually be represented as:

Tool
 |
 +-- name
 +-- description
 +-- input schema
 +-- execution logic
 +-- output

This allows the model or agent to reason about what capabilities are available.

A simplified workflow looks like:

User
 |
 | "What is the weather in Madrid?"
 v
LLM
 |
 | discovers get_weather
 v
MCP Client
 |
 | tools/call
 v
MCP Server
 |
 | call weather API
 v
Weather API
 |
 v
MCP Server
 |
 v
MCP Client
 |
 v
LLM
 |
 v
User

The important idea is:

Tools give AI applications the ability to interact with real systems.

Instead of simply generating text, an agent can request that an external operation be executed.

6. Type Safety With Schemas

One of the major themes in the mcp-use TypeScript ecosystem is type-safe tool definitions.

For example:

import { MCPServer } from "mcp-use";
import { z } from "zod";

const server = new MCPServer({
  name: "weather-app",
  title: "Weather App",
  version: "1.0.0",
});

const weatherInput = z.object({
  city: z.string().describe("City to look up"),
});

const weatherOutput = z.object({
  city: z.string(),
  temperature: z.number(),
  conditions: z.string(),
});

server.tool(
  {
    name: "get-weather",
    title: "Get weather",
    description: "Get the current weather for a city",
    inputSchema: weatherInput,
    outputSchema: weatherOutput,
  },
  async ({ city }) => {
    const weather = {
      city,
      temperature: 22,
      conditions: "Sunny",
    };

    return {
      content: [
        {
          type: "text",
          text: `Weather in ${city}: ${weather.conditions}, ${weather.temperature}°C`,
        },
      ],
      structuredContent: weather,
    };
  },
);

Here, Zod defines the contract.

                 Zod schema
                     |
                     v
             +---------------+
             | Input contract |
             +---------------+
                     |
                     v
                  Tool
                     |
                     v
             +----------------+
             | Output contract|
             +----------------+

Instead of passing arbitrary JSON around, developers can define explicit contracts.

For example:

Input

city: string

and:

Output

city: string
temperature: number
conditions: string

This becomes increasingly valuable as MCP applications become larger.

Schemas provide:

Validation
Predictability
Type safety
Better developer experience
More reliable tool integration

The key principle is:

Schemas turn AI/tool communication into a defined contract.

7. mcp-use and Agents

An MCP server becomes considerably more useful when an agent can reason over the available tools.

The architecture becomes:

                    User
                      |
                      v
                    Agent
                      |
              +-------+-------+
              |               |
             LLM          MCP Client
              |               |
              +-------+-------+
                      |
                 MCP Servers
                      |
        +-------------+-------------+
        |             |             |
      GitHub        Database      Browser

The agent can determine which capability is relevant to a particular request.

For example:

"Find the latest customer issues, analyze the data, and create a summary."

The agent might perform:

1. Search database
       ↓
2. Read customer records
       ↓
3. Analyze information
       ↓
4. Generate structured result
       ↓
5. Return summary

This is where MCP becomes particularly powerful for agentic applications.

The agent provides the reasoning and orchestration.

MCP provides the standardized capability layer.

The MCP servers provide the actual tools and data.

So:

Agent
  ↓
Reason
  ↓
Select capability
  ↓
MCP tool
  ↓
External system
  ↓
Result
  ↓
Agent
  ↓
Next step

8. Connecting Multiple MCP Servers

A particularly useful capability is working with multiple MCP servers.

Imagine an enterprise agent with:

                 AI Agent
                    |
               mcp-use Client
                    |
        +-----------+-----------+
        |           |           |
      GitHub      Database    Browser
       MCP          MCP         MCP
        |           |           |
     GitHub        SQL       Playwright

The agent can potentially combine capabilities from multiple systems.

For example:

"Find the open GitHub issues related to customers who experienced payment failures last month."

The agent could conceptually perform:

GitHub MCP
    |
    | Find issues
    v
Issue data

Database MCP
    |
    | Query payment failures
    v
Customer data

          ↓

       Agent
          |
          v
   Correlate information
          |
          v
       Answer

This is one of the compelling use cases for MCP.

Instead of building one giant integration, capabilities can be exposed through separate MCP servers.

This creates a more modular architecture:

             Agent
               |
           MCP Client
               |
      +--------+--------+
      |        |        |
     MCP      MCP      MCP
   Server   Server   Server
      |        |        |
     CRM       DB     GitHub

Each server can specialize in a particular domain.

9. MCP Resources vs Tools

A common MCP architectural distinction is between resources and tools.

A useful mental model is:

Resources → information/context

Tools → actions/operations

For example:

Resource:

database://customers/123

The resource represents information that can be accessed.

Whereas:

Tool:

update_customer(customer_id, data)

represents an operation that can be executed.

The distinction can be summarized as:

RESOURCE
    ↓
"Give me information."

TOOL
    ↓
"Do something."

This is important because not every capability should be modeled as an executable action.

For example:

Customer profile
       ↓
   Resource

while:

Update customer
       ↓
      Tool

A simple memory trick is:

Resource = information. Tool = action.

10. Interactive MCP Apps

One of the areas where the current TypeScript version of mcp-use goes beyond a basic MCP server framework is interactive Views and MCP Apps.

Traditional tool calling might look like:

Tool
 |
 v
Text

An MCP App can instead provide:

Tool
 |
 v
Structured data
 |
 v
React View
 |
 v
Interactive UI

For example, imagine a weather tool.

Instead of returning:

Weather in Madrid:
22°C
Sunny

the application could render:

+--------------------------------+
|         Madrid Weather         |
|                                |
|             ☀️                 |
|                                |
|             22°C               |
|             Sunny              |
|                                |
|        [ Refresh ]             |
+--------------------------------+

This is a significant conceptual shift.

The application is no longer limited to:

AI → Tool → Text

It can become:

AI → Tool → Structured Data → UI

This opens the door to:

Interactive dashboards
Maps
Data visualizations
Diagrams
Search interfaces
Configuration panels
Approval workflows
Business applications

The key idea is:

MCP can become not only a capability interface, but also part of an interactive application experience.

11. Why UI + MCP Is Interesting

Traditional tool calling looks like:

LLM
 |
 | call tool
 v
Tool
 |
 v
Result
 |
 v
LLM
 |
 v
Text response

With an MCP App:

LLM
 |
 | call tool
 v
MCP Server
 |
 +---- structured result
 |
 +---- UI/View
        |
        v
      User

This creates a different interaction model.

For example, an AI assistant could call a data-analysis tool and return:

Tool
 ↓
Query database
 ↓
Analyze data
 ↓
Generate structured result
 ↓
Render chart
 ↓
User interacts with chart

Possible applications include:

Data analysis

Database
   ↓
MCP
   ↓
Agent
   ↓
Chart

Maps

Location data
     ↓
MCP
     ↓
Agent
     ↓
Interactive map

Business workflows

Agent
  ↓
MCP Tool
  ↓
Approval UI
  ↓
Human decision
  ↓
Action

This is particularly interesting for enterprise applications because the AI does not necessarily have to produce a long textual response for every task.

It can produce an interactive application experience.

12. The mcp-use Inspector

Debugging AI applications can be difficult.

Consider the following chain:

LLM
 ↓
Agent
 ↓
MCP Client
 ↓
MCP Server
 ↓
Database

If something goes wrong, where is the problem?

Did the model select the wrong tool?
Was the schema incorrect?
Did the MCP client send the wrong arguments?
Did the server reject the request?
Did the database fail?

This is why an MCP Inspector is valuable.

The current TypeScript mcp-use stack includes an Inspector that allows developers to inspect MCP servers and invoke tools during development.

A typical development workflow becomes:

Write tool
    ↓
Run server
    ↓
Open Inspector
    ↓
Inspect schema
    ↓
Invoke tool
    ↓
Inspect result
    ↓
Debug
    ↓
Modify code
    ↓
Repeat

The development server can be started with:

mcp-use dev

The Inspector provides a visual environment for examining and testing MCP capabilities.

This shortens the development feedback loop considerably.

13. Testing MCP Servers From the CLI

Another useful feature is the mcp-use CLI.

For example:

npx mcp-use client connect dev http://localhost:3000/mcp

You can then inspect available tools:

npx mcp-use client dev tools list

And invoke a tool:

npx mcp-use client dev tools call get-weather city=Tokyo

The basic workflow is:

MCP Server
    ↓
CLI
    ↓
Discover tools
    ↓
Inspect schema
    ↓
Call tool
    ↓
Inspect result

This is useful for:

Development
Debugging
Testing
Automation
CI/CD workflows

It also provides a convenient way to test MCP capabilities without relying exclusively on a graphical AI client.

The important idea is:

MCP capabilities can be developed and tested like other software interfaces.

14. Authentication

Once MCP moves beyond localhost, authentication becomes critical.

An MCP architecture needs to consider:

Authentication
Authorization
Secrets
HTTPS
Token management
Least privilege

A simplified architecture is:

AI Agent
    |
MCP Client
    |
Authentication
    |
MCP Server
    |
External System

For example, an enterprise MCP server might require OAuth or another authentication mechanism before allowing the client to access protected capabilities.

Credentials should never be hardcoded into source code.

Avoid:

API_KEY = "my-secret-key"

Instead use mechanisms such as:

Environment variables
Secret managers
OAuth
Managed identity

depending on the architecture.

Authentication answers:

"Who are you?"

Authorization answers:

"What are you allowed to do?"

These are different security concerns.

For an AI agent, authorization is particularly important because tools can perform real actions.

For example:

Agent
 |
 +-- READ customer data
 |
 +-- READ tickets
 |
 +-- CREATE ticket
 |
 X-- DELETE production database

The principle is:

Give the agent only the capabilities it actually needs.

15. Structured Output

Another important capability for agentic applications is structured output.

Instead of asking an agent to return:

"The temperature is 22 degrees
and it is sunny."

you can define a schema:

from pydantic import BaseModel

class WeatherInfo(BaseModel):
    city: str
    temperature: float
    condition: str
    humidity: int

The result can then be represented as structured data:

{
  "city": "Madrid",
  "temperature": 22,
  "condition": "Sunny",
  "humidity": 45
}

This becomes especially useful when the agent's output is consumed by another system.

For example:

LLM
 |
 v
Agent
 |
 v
Structured Output
 |
 +----> Database
 |
 +----> API
 |
 +----> Dashboard
 |
 +----> Workflow

Compare this with unstructured text:

"The customer is high risk and
the temperature is 22 degrees..."

A machine cannot reliably consume arbitrary text without additional parsing.

With structured output:

risk_level: "high"
temperature: 22

the downstream system knows exactly what each field means.

The key principle is:

AI-generated data becomes much more useful when it has a predictable contract.

16. Integrating With Existing Agent Frameworks

Using mcp-use does not necessarily mean abandoning existing agent frameworks.

The MCP layer can sit underneath an existing orchestration framework.

Conceptually:

             MCP Servers
                  |
                  v
              mcp-use
                  |
             MCP Adapter
                  |
                  v
             Agent Framework
                  |
                  v
                Agent
                  |
                  v
                 LLM

For example, an agent framework can remain responsible for:

Planning
Reasoning
Memory
Agent execution
Workflow orchestration

while MCP provides standardized access to external capabilities.

This creates a useful separation:

Agent framework
      ↓
"How should I reason and orchestrate?"

MCP
      ↓
"What external capabilities can I use?"

This is an important architectural pattern.

MCP can become the standardized capability layer, while your preferred agent framework remains responsible for orchestration.

17. Python vs TypeScript

The mcp-use ecosystem spans both Python and TypeScript.

The developer experience differs depending on the type of application you are building.

Python

Python is particularly attractive for applications centered around:

AI
Agents
Data
Machine Learning
LLM integrations
Python AI ecosystem

A typical architecture might be:

Python
   |
Agent
   |
LLM
   |
mcp-use
   |
MCP Servers

Python also fits naturally into existing AI and data workflows.

TypeScript

The TypeScript ecosystem becomes particularly interesting for:

MCP Servers
MCP Apps
React
Interactive Views
Full-stack applications
CLI tooling
Inspector

A typical architecture might be:

TypeScript
     |
MCP Server
     |
Tools
     |
Structured Data
     |
React View
     |
Interactive UI

The current TypeScript framework provides native support for Views, MCP Apps, typed contracts, Inspector tooling, and CLI workflows.

Simplified comparison

Area	Python	TypeScript
MCP clients	✓	✓
MCP servers	✓	✓
Agent development	✓	✓
LLM integrations	✓	✓
Structured schemas	Pydantic	Zod
Data/AI workflows	✓	✓
React MCP Views	—	✓
MCP Apps	—	✓
Inspector/CLI	Ecosystem	Native tooling

The choice therefore depends heavily on the application.

If your architecture is primarily:

AI + Data + Python + Agents

Python can be a natural choice.

If your architecture is:

MCP Server + React UI + MCP App + TypeScript

the TypeScript stack becomes particularly interesting.

18. A Simple End-to-End Architecture

Putting everything together, a modern MCP application can look like this:

                         USER
                           |
                           v
                    +-------------+
                    | AI Interface|
                    +-------------+
                           |
                           v
                    +-------------+
                    |    Agent    |
                    +-------------+
                           |
                    +------+------+
                    |     LLM     |
                    +------+------+
                           |
                    +------+------+
                    |  mcp-use    |
                    | MCP Client  |
                    +------+------+
                           |
              +------------+------------+
              |            |            |
              v            v            v
          GitHub MCP   Database MCP  Browser MCP
              |            |            |
              v            v            v
           GitHub         SQL        Web/API

The responsibilities are separated.

User

Defines the goal.

AI Interface

Provides the interaction layer.

Agent

Orchestrates the task.

LLM

Provides reasoning and language generation.

mcp-use

Provides the application infrastructure around MCP.

MCP Client

Connects the application to MCP servers.

MCP Servers

Expose tools and resources.

External Systems

Provide the actual data and perform the actual actions.

This separation creates a modular architecture.

19. What mcp-use Actually Adds

It is useful to think about the entire technology stack in layers.

Layer 1 — LLM

Examples include:

OpenAI
Anthropic
Google
Local models

The model provides reasoning and generation.

Layer 2 — Agent

The agent determines:

What should I do?

Which tool should I call?

What information is missing?

What should happen next?

The agent is responsible for orchestration.

Layer 3 — mcp-use

mcp-use provides developer-oriented abstractions around MCP.

Depending on the ecosystem, this includes:

MCP Clients
MCP Servers
Agents
Tools
Structured contracts
Inspector
CLI
Views
MCP Apps

Layer 4 — MCP

MCP provides the standardized protocol through which AI applications communicate with MCP servers.

Conceptually:

AI Application
      |
   MCP Client
      |
      | MCP
      |
   MCP Server

Layer 5 — MCP Servers

MCP servers expose capabilities such as:

Tools
Resources
Prompts

For example:

GitHub MCP
Database MCP
Browser MCP
CRM MCP
Cloud MCP

Layer 6 — External Systems

These are the systems where the actual data and actions exist:

Databases
APIs
GitHub
Cloud platforms
Filesystem
SaaS applications
Enterprise systems

The complete architecture therefore becomes:

┌─────────────────────────────┐
│            User             │
└──────────────┬──────────────┘
               │
┌──────────────▼──────────────┐
│        AI Application       │
│                             │
│       LLM + Agent + UI      │
└──────────────┬──────────────┘
               │
┌──────────────▼──────────────┐
│          mcp-use            │
│                             │
│ Client / Agent / Server     │
│ Inspector / CLI / Views     │
└──────────────┬──────────────┘
               │
┌──────────────▼──────────────┐
│            MCP              │
│       Protocol Layer         │
└──────────────┬──────────────┘
               │
       ┌───────┼────────┐
       │       │        │
       ▼       ▼        ▼
     APIs   Databases  Tools

The key architectural insight is:

mcp-use is not the protocol itself. It is a development framework built around the MCP ecosystem.

MCP provides the standardized capability layer.

The agent provides orchestration.

The LLM provides reasoning.

The MCP servers expose capabilities.

And the external systems provide the underlying data and actions.

That separation is what makes the architecture powerful and modular.

mcp-use library powered by Manufact

Ignacio Gonzalez Bohorquez — Mon, 28 Sep 2026 16:17:04 +0000

mcp-use Library

Summary Video: https://www.youtube.com/shorts/lhsUSWES0_k

Manufact · GitHub

Manufact is the cloud platform for Model Context Protocol. We open-sourced mcp-use, the fullstack framework to build MCP Servers & MCP Apps for ChatGPT / Claude - Manufact

github.com

# Skills, MCP, RAG, and Memory: The Four Ways AI Agents Actually Learn Things

Ignacio Gonzalez Bohorquez — Sun, 27 Sep 2026 00:23:46 +0000

Why "just add more context" isn't a strategy — and what these four building blocks are really for

Every language model, on its own, only knows what was in its training data. It has no access to your company's HR system, no memory of yesterday's debugging session, and no idea how your team likes a 500 error triaged. Four mechanisms have emerged as the standard ways engineers close that gap — Retrieval-Augmented Generation, the Model Context Protocol, Agent Skills, and agent memory — and they're not interchangeable. Each answers a different question.

RAG: Retrieval-Augmented Generation — knowledge someone wrote down

RAG's job is to ground a model's answer in documents it wasn't trained on — a policy handbook, a manual, a knowledge base — by pulling in the relevant passage before the model generates a response, rather than hoping the fact is buried somewhere in its parameters.

The technique traces back to a 2020 paper out of Facebook AI Research, UCL, and NYU, which combined a pre-trained sequence-to-sequence model with a dense vector index of retrievable documents, treating retrieval as a differentiable step rather than a separate lookup bolted onto generation. The paper compared two formulations — one conditioning on the same retrieved passages across a whole generated sequence, the other using different passages per token — and found RAG models generated more specific, diverse, and factual language than a purely parametric baseline.

In practice, RAG runs a five-step loop: a user asks a question, the system converts it into a search query and retrieves matching passages (usually via semantic/vector search), those passages get returned, they're stitched into an augmented prompt alongside the original question, and the model generates a grounded answer — ideally with the source passage cited so the answer can be checked. This is the right tool when the knowledge in question is static and already written down somewhere: policy docs, runbooks, dependency maps, product manuals.

MCP: Model Context Protocol — knowledge (and action) that lives in a system

Where RAG is about knowing more, the Model Context Protocol is about doing more. MCP is a standardized client-server protocol that lets an agent connect to external systems — databases, SaaS tools, internal APIs — to read live data or actually take action, rather than searching through static documents.

Anthropic open-sourced MCP in November 2024, describing it as a new standard for connecting AI assistants to the systems where data lives, including content repositories, business tools, and development environments, aimed at helping models produce better, more relevant responses. The workflow looks different from RAG's retrieval loop: the agent connects to an MCP server and discovers what tools are available, reads each tool's schema to understand its inputs and outputs, plans which tools to call and in what order, executes structured calls through the MCP runtime, and integrates the results back into its reasoning — potentially triggering more calls before finalizing an answer.

The distinction matters in practice: if you ask "how many vacation days do I have left," that's not sitting in a PDF anywhere — it's a live number in an HR system, and RAG can't fetch it. MCP can, because it's built to call tools and read (or write to) live systems, not just retrieve static text.

Agent Skills: procedural knowledge — knowing how to do a specific task

The newest of the four addresses something neither RAG nor MCP covers well: repeatable procedures and judgment calls. A skill is a folder containing a SKILL.md file with instructions, and optionally supporting scripts or reference files, that tells an agent how to carry out a specific kind of task — say, triaging a production error, or building a slide deck in a house style.

Anthropic introduced Agent Skills on October 16, 2025, and published it as an open standard for cross-platform portability on December 18, 2025, after which other coding tools began adopting the same SKILL.md format. The key design idea is progressive disclosure: at startup, an agent pre-loads only the name and description of every installed skill into its system prompt — enough to know when each skill is relevant without loading all of it into context — and only reads the full body of a skill's instructions once it decides that skill actually applies to the current task. This is why a skill can reference arbitrarily large supporting material (scripts, templates, longer docs) without bloating the context window by default — only the parts actually needed get pulled in, and only when needed.

Skills don't give an agent new reach, though. A skill can tell an agent "check the error rate, then check recent deployments," but the agent still needs some other mechanism — usually MCP — to actually read that error rate from a dashboard or logging system in the first place.

Memory: what the agent picks up on its own

Memory is the odd one out because, unlike the other three, it isn't knowledge someone deliberately curated for the agent — it's knowledge the agent accumulates itself, from its own past interactions. The most cited organizing framework for this comes from a Princeton research team, whose 2024 paper "Cognitive Architectures for Language Agents" (CoALA) organizes an agent's information storage into working memory and long-term memory, with the latter further divided into distinct categories, alongside a structured action space and a generalized decision-making loop. In applied form, that breaks into four types:

Working memory — the live context window: the current conversation, loaded files, system instructions. Volatile; gone when the session ends.
Semantic memory — general facts, conventions, and documentation the agent should always have on hand, often implemented today as simple project-level markdown files (a CLAUDE.md at a repo root, for instance) rather than a vector database.
Procedural memory — how to do things; this is where Agent Skills technically lives, using the same progressive-disclosure pattern described above.
Episodic memory — a distilled record of what happened in past sessions and what the agent learned from them, e.g., "last time this exact error occurred, the real cause wasn't in the runbook." This is the hardest to get right, because deciding what's worth keeping — and when it becomes stale — is a genuine engineering problem, not a solved one.

Not every agent needs all four. A simple reflex agent might only need working memory; a narrow support bot might add procedural memory for a specific skill; a general-purpose coding agent typically needs all four to actually improve over time rather than repeating the same mistakes every session.

Where the four overlap

A common source of confusion is that "semantic memory" and RAG can sound like the same thing — both are about facts written down somewhere. The practical difference is mechanism and scope: RAG is a retrieval pipeline pointed at a large, often external corpus, fetched on demand via search; the semantic-memory pattern in a coding agent is usually a small, fixed file loaded wholesale into every session, not searched. Similarly, "procedural memory" and "Agent Skills" aren't two different things — Skills is simply the concrete, shipped implementation of the procedural-memory concept CoALA described in the abstract two years earlier.

It's also worth being skeptical of any framing that treats these four as mutually exclusive choices. In real systems they compose: an MCP server can call out to a RAG pipeline as one of its tools when a user's question is better answered by document retrieval than by hitting a live system; a coding agent's skill can instruct it to use a specific MCP tool as one of its steps; and episodic memory can record which skill or MCP call actually solved a problem last time, so the agent doesn't have to rediscover it.

The takeaway

None of these four are competing paradigms — they're answers to four different questions an agent runs into constantly: what's written down, what's live, what's the procedure, and what have I learned. The real architecture question isn't "RAG or MCP" or "Skills or Memory" — it's recognizing which of the four a given task actually needs, and building the connective tissue (security, governance, context budgeting) to let them work together without drowning the model in irrelevant context.

MCP vs. APIs: Why AI Agents Needed Their Own Protocol

Ignacio Gonzalez Bohorquez — Sat, 26 Sep 2026 15:21:55 +0000

MCP vs. APIs: Why AI Agents Needed Their Own Protocol
Understanding the "USB-C for AI" standard that OpenAI, Google, and thousands of developers have now bought into

For as long as software has talked to other software, it's done so through APIs. You read the docs, hardcode the endpoint, parse the response, and if the API changes, you go fix your code. That's worked fine for two decades of human-written integrations. It falls apart once the thing calling the API is a language model instead of a developer.

That's the gap the Model Context Protocol (MCP) was built to close. Anthropic open-sourced MCP on November 25, 2024, as "a new standard for connecting AI assistants to the systems where data lives." (Anthropic) A year later, it's no longer just an Anthropic experiment: OpenAI adopted MCP in its Agents SDK in March 2025 and has since rolled it out across ChatGPT and its Responses API, Google DeepMind added support to Gemini, and companies including GitHub, Block, Replit, Sourcegraph, and Zapier have built it into their platforms. Over 16,000 MCP servers now exist in the wild. (Zuplo)

The problem: N models × M tools

Imagine building an AI support chatbot for an e-commerce platform. A customer asks where their order is — that's a Postgres query. They ask about product availability — that's an Elasticsearch call. They want a refund — that's Stripe, plus a Slack notification to finance. Each integration needs its own auth, error handling, and response parsing. Now your manager wants to try GPT-4 alongside Claude, and every integration needs duplicating. Add a third model later, and you're maintaining a matrix of glue code that grows multiplicatively with each new model or data source.

Traditional REST APIs weren't built for this because they weren't built for AI consumers at all. A raw Kubernetes API response for a pod's status can run to hundreds of nested JSON fields — fine for a developer who knows what they want, noisy for a model that has to infer relevance. MCP sits between the model and the API, translating a sprawling native response into something like "pod my-app: 3/3 containers ready, no restarts" — only what the model needs.

What MCP actually defines

Architecturally, MCP has three pieces: a host (the AI application — Claude Desktop, Cursor, a custom backend), an MCP client inside that host, and one or more MCP servers, each exposing a tool or data source. Communication runs over JSON-RPC 2.0, using stdio for local processes or Streamable HTTP for remote services — the latter having replaced an earlier HTTP+SSE transport in the March 2025 spec revision. The current dated spec is 2025-11-25.

Servers expose capabilities through standardized primitives: tools (callable functions with a JSON Schema input, like create_refund), resources (read-only, URI-addressable data such as file contents), and prompts (templates suggesting how to use the server). Newer revisions added client-side primitives too, like elicitation, which lets a server ask the user a structured follow-up question mid-task instead of guessing.

What makes this useful in practice is dynamic discovery. On startup, an MCP client sends tools/list to each server and gets back a machine-readable catalog — names, descriptions, schemas. Add a new tool to a server later, and the client picks it up on the next connection, with no client-side code change required. A traditional REST integration needs a developer to update the calling code before a new endpoint can be used at all.

Not the same as function calling

If you've built with a model provider's SDK, you've used function calling — describing a function in JSON Schema so the model can decide when to invoke it. MCP doesn't replace this; function calling is how a model expresses intent to call something, while MCP standardizes how tools are discovered and invoked consistently across servers and providers, so you're not rewriting that glue layer for every model and every API.

One claim worth being precise about: MCP is often described as "stateful" where REST is inherently "stateless." More accurately, it's the host application that retains conversation history and prior tool results — MCP standardizes that pattern rather than the wire protocol having some property REST categorically lacks. You could build stateful orchestration on top of plain REST yourself; MCP just means you don't build it from scratch per integration.

Security: keeping secrets out of the model

A genuinely useful design decision is where credentials live. Naively, an AI agent would need its own API key for every service it might call — uncomfortable given how unpredictable model behavior can be. MCP servers hold those secrets instead: the model requests an action, the server authenticates and executes it, and the model never sees a key or token.

This is formalized in the spec, not just convention. The March 2025 release added an OAuth 2.1-based authorization framework with mandatory PKCE, and MCP servers are explicitly categorized as OAuth Resource Servers, discoverable via a standard metadata endpoint — letting a server plug into existing enterprise SSO rather than inventing bespoke auth. That layer applies to remote, HTTP-based servers specifically; local stdio servers (still common for filesystem or local-database access) pull credentials from the environment instead, a meaningfully different trust model worth knowing before deciding where to run a server.

Real limits, rarely mentioned

MCP is an interface standardizer, not a capability multiplier. If your Postgres integration only has read access, wrapping it in MCP won't make it writable — the underlying API is still the contract.

Dynamic discovery cuts both ways, too. The same property that lets a client pick up new tools automatically also means it can adopt modified tool definitions from a server at runtime without a human necessarily reviewing them. Security researchers have flagged this over the past year as "tool poisoning" — a compromised server altering a tool's description after a client has already trusted it, or using tool outputs to smuggle in prompt injection. That's a real trade-off against the convenience of "just ask the server what it can do," and worth a security review before exposing any MCP server beyond your own machine.

Aggregators: one server, many tools

Not every team wants a separate server per API. Zapier runs a single MCP server connecting to more than 9,000 apps and 40,000+ actions. (Zapier docs) It doesn't hand a client all 40,000 action definitions upfront — that would overwhelm most context windows. Instead, its "Agentic" mode exposes around 14 static meta-tools, and the agent uses functions like discover_zapier_actions and enable_zapier_action to find and enable specific actions mid-conversation — a cleaner illustration of dynamic discovery than a flat tool count suggests.

Where it's headed

Anthropic recently donated MCP to the Linux Foundation's new Agentic AI Foundation, joining Block's goose and OpenAI's AGENTS.md as founding projects. (Anthropic) That's a deliberate move to keep MCP vendor-neutral — a meaningful signal given that OpenAI and Google now depend on it too.

The takeaway

MCP doesn't replace the APIs you already have — Stripe still has its REST API. What it replaces is the custom glue code you'd otherwise write for every model-and-tool pairing: one client speaking one protocol to any number of servers, runtime discovery instead of hardcoded endpoint lists, standardized OAuth instead of ad hoc credentials. A year in, that's proven compelling enough that Anthropic's two biggest competitors adopted it rather than build their own.

MCP Roles & Tool-Call Flow

Ignacio Gonzalez Bohorquez — Fri, 25 Sep 2026 15:00:17 +0000

DEV Community: Ignacio Gonzalez Bohorquez

Following One Question Through the MCP Stack: 20 Steps from Prompt to Answer

Two Protocols, Three Translations: How a Host Bridges MCP and an LLM Provider API

1. The Architecture

Phase 1 — Discovery

Steps 1–6

Step 1 — The User asks a question

Step 2 — The Host starts discovery

Step 3 — The Client sends tools/list

Step 4 — The Server reads its tool registry

Step 5 — The Server returns the tool list

Step 6 — The Client gives the tools to the Host

Phase 2 — Translation and LLM Decision

Steps 7–10

Step 7 — Translation #1

Step 8 — The Host sends the prompt and tools to the LLM

Step 9 — The LLM decides which tool to use

Step 10 — The LLM returns its tool decision

Phase 3 — Execution

Steps 11–16

Step 11 — Translation #2

Step 12 — The Client sends tools/call

Step 13 — The Server looks up the tool

Step 14 — The Server validates the arguments

Step 15 — The Server executes the handler

Step 16 — The Server returns the result

Phase 4 — Result and Response

Steps 17–20

Step 17 — The Client receives the result

Step 18 — Translation #3

Step 19 — The LLM generates the final answer

Step 20 — The User sees the final answer

The Three Translations

Translation #1

Translation #2

Translation #3

The Complete Flow

The Complete 20-Step Lifecycle

Phase 1 — Discovery

Phase 2 — Translation and LLM Decision

Phase 3 — Execution

Phase 4 — Result and Response

TypeScript Example

Python Example

A Simplified End-to-End Host

Why This Architecture Matters

MCP Is Not the LLM Provider API

The MCP Server Does Not Tell the LLM What to Do

The Most Important Security Boundary

The Final Mental Model

MCP-USE Explained: Building Full-Stack AI Agents and MCP Apps with TypeScript and Python

Table of Contents

1. What Problem Does MCP Solve?

2. MCP Is Not an Agent Framework

LLM

Agent

MCP Client

MCP

MCP Server

External Systems

3. What Is mcp-use?

4. The Dual Nature of mcp-use

Server Side

Client / Agent Side

5. MCP Tools: The Bridge Between LLMs and Real Systems

6. Type Safety With Schemas

7. mcp-use and Agents

8. Connecting Multiple MCP Servers

9. MCP Resources vs Tools

10. Interactive MCP Apps

11. Why UI + MCP Is Interesting

Data analysis

Maps

Business workflows

12. The mcp-use Inspector

13. Testing MCP Servers From the CLI

14. Authentication

15. Structured Output

16. Integrating With Existing Agent Frameworks

17. Python vs TypeScript