Building an MCP Client

In this lesson we’ll build a minimal end-to-end MCP (Model Context Protocol) client and server. You’ll see a complete example for:

MCP configuration (mcp.json) that points a client to a server
A minimal MCP server exposing tools, resources, and prompts
A minimal client that lists tools, calls tools, reads resources, and fetches prompts
How to wire up Contexts, Roots, Sampling, and Elicitation so server and client coordinate during long-running or interactive operations

Many tools and IDEs (for example, Cursor AI or Claude Code for Beginners) automatically read an mcp.json configuration to find MCP servers. This guide shows how to implement a custom client and server if you want more control.

Example MCP configuration

A simple mcp.json pointing a client to an MCP server:

{
  "mcpServers": {
    "flight-mcp": {
      "url": "https://joyair.com/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

This tells the client where the MCP server is and supplies any request headers (for example, API keys).

Overview: Server and Client roles

Server (FastMCP) — defines tools, resources, and prompts and can request client-side LLM sampling or elicit user input.
Client (ClientSession) — connects to the server, enumerates capabilities, calls tools, reads resources, returns prompts, answers elicitations, and performs sampling when requested.

We first create a super-simple MCP server, then a client that calls it.

Server (FastMCP) — minimal example

This FastMCP server exposes a tool, a resource, and a prompt:

from mcp.server.fastmcp import FastMCP
from mcp.server.context import Context

mcp = FastMCP("flight-server")

@mcp.tool()
async def search_flights(origin: str, destination: str):
    return {"flights": ["flight1", "flight2"]}

@mcp.resource("flight://status/{id}")
async def get_status(id: str):
    return {"status": "on_time"}

@mcp.prompt()
async def find_flight(details: str):
    return f"Suggestions for {details}"

if __name__ == "__main__":
    # Start an HTTP MCP server on port 8080
    mcp.run(transport="http", port=8080)

@mcp.tool() — registers a callable tool (synchronous or async).
@mcp.resource(...) — exposes a resource accessible via a URI pattern.
@mcp.prompt() — returns a text prompt the client can request.

Client (ClientSession) — minimal example

This client connects to the server, lists available tools, calls a tool, reads a resource, and fetches a prompt:

from mcp.client.session import ClientSession
import asyncio

async def client():
    # Connect to the MCP server
    client = ClientSession("http://localhost:8080/mcp")

    async with client:
        # List what's available
        tools = await client.list_tools()
        print("Available tools:", tools)

        # Use tools
        flights = await client.call_tool("search_flights", {
            "origin": "SFO",
            "destination": "JFK"
        })
        print("search_flights result:", flights)

        # Read resources
        status = await client.read_resource("flight://status/UA123")
        print("resource status:", status)

        # Get prompts
        advice = await client.get_prompt("find_flight", {
            "details": "SFO to JFK"
        })
        print("prompt advice:", advice)

asyncio.run(client())

Client-side convenience methods you will use frequently include list_tools(), call_tool(), read_resource(), and get_prompt(). Use them to discover and invoke the server-side capabilities.

Contexts — server-to-client progress & logging

Contexts let a server stream messages back to the client during long-running tool executions (progress updates, info logs, or debug messages). On the server side, the Context object provides helpers such as:

ctx.info(...) — send informational messages
ctx.report_progress(...) — send progress updates
ctx.debug(...) — send debug messages

The client receives and can surface those updates in UI elements or logs.

Roots — controlled client filesystem access

Roots are client-defined folders the MCP server may access or reference. Think of them as shared folders: you explicitly expose only safe paths so the server cannot access the entire client filesystem. The client provides allowed roots when creating a session and the server can inspect them with context.session.list_roots().

A slide titled "Roots" showing an MCP Client (pink) connected by dashed green lines to an MCP Server (teal), with a file tree below listing /home/projects/flygpt, /resources, new-flight-policy.txt and refund-policy.txt. A left sidebar highlights menu items "Roots," "Sampling," and "Elicitation."

Only expose directories you trust. Roots grant the server limited access to client files — avoid adding sensitive or system directories.

Sampling — client-driven LLM calls

Why sampling? A server may request that the client perform LLM generation instead of hosting or calling an LLM itself. This keeps the server lightweight and lets each client control model selection, token limits, and billing. Server requests sampling via the context/session; the client supplies a sampling handler when creating the session. Client-side sampling handler example:

# Client-side sampling handler
from mcp.client.session import ClientSession
from mcp.types import SamplingMessage, TextContent
import asyncio

async def call_my_llm_service(prompt: str) -> str:
    # Replace this with your LLM invocation
    # Example placeholder: echo prompt back for demo
    return f"LLM response for: {prompt}"

async def my_llm_handler(messages, params, context):
    # 1. EXTRACT prompt from messages
    prompt = messages[0].content.text

    # 2. GENERATE response (call your LLM)
    response_text = await call_my_llm_service(prompt)

    # 3. RETURN generated text as a SamplingMessage/TextContent-like structure
    # The exact return type may depend on the client API; return plain text here.
    return response_text

async def run_client():
    client = ClientSession("http://localhost:8080/mcp",
                           sampling_handler=my_llm_handler)
    async with client:
        await client.initialize()
        # client remains ready to handle sampling requests from the server

asyncio.run(run_client())

Server-side tool requesting sampling via the context:

from mcp.server.fastmcp import FastMCP
from mcp.server.context import Context
from mcp.types import SamplingMessage, TextContent

mcp = FastMCP("sampling-server")

@mcp.tool()
async def generate_content(topic: str, ctx: Context):
    # 1. CREATE prompt
    prompt = f"Write something about {topic}"

    # 2. REQUEST LLM generation from the client via sampling
    result = await ctx.session.create_message([
        SamplingMessage(role="user", content=TextContent(text=prompt))
    ])

    # 3. RETURN generated content (result content structure may vary)
    return result.content.text

Elicitation — prompt end users for structured input

Elicitation allows the server to ask the client to prompt the end user for more data during tool execution. The server calls ctx.elicit(...) with a message and optional schema. The client must provide an elicitation callback that captures, validates, and returns the structured response. Client-side elicitation handler (streamable HTTP transport example):

from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamablehttp_client
from mcp.types import ElicitRequestParams, ElicitResult
import asyncio

async def handle_elicitation(context, params: ElicitRequestParams) -> ElicitResult:
    print(f"🔔 Server requests: {params.message}")

    # 👥 Get real user input (blocking input for demo; adapt for your UI)
    name = input("Enter your name: ")
    age = int(input("Enter your age: "))

    user_response = {"name": name, "age": age}

    # 📝 Return structured response expected by the server
    return ElicitResult(action="accept", data=user_response)

async def main():
    # Connect to a streamable HTTP MCP server; adjust URL/port as needed
    async with streamablehttp_client("http://localhost:8000") as (read, write, _):
        async with ClientSession(read, write,
                                 elicitation_callback=handle_elicitation) as session:
            await session.initialize()

            # 🚀 Call tool that uses elicitation on the server side
            result = await session.call_tool("ask_user_info", {})
            print(f"✅ Result: {result}")

asyncio.run(main())

Server-side tool using elicitation (FastMCP):

from mcp.server.fastmcp import FastMCP, Context
from pydantic import BaseModel

mcp = FastMCP("elicitation-demo")

class UserInfo(BaseModel):
    name: str
    age: int

@mcp.tool()
async def ask_user_info(ctx: Context) -> str:
    # 🔔 Request structured input from user
    result = await ctx.elicit(
        message="Please provide your information:",
        schema=UserInfo
    )

    # ✅ Use validated data
    user_data = result.data
    return f"Hello {user_data.name}, {user_data.age}"

# Start server using the streamable HTTP transport
if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Feature quick-reference

Feature	Client API	Server API / Usage
Discover tools	`await client.list_tools()`	`@mcp.tool()`
Invoke tool	`await client.call_tool("name", params)`	`@mcp.tool()`
Read resource	`await client.read_resource("scheme://...")`	`@mcp.resource("...")`
Get prompt	`await client.get_prompt("name", params)`	`@mcp.prompt()`
Sampling (client-run LLM)	provide `sampling_handler` to `ClientSession`	call `ctx.session.create_message([...SamplingMessage...])`
Elicitation (ask user)	provide `elicitation_callback` (returns `ElicitResult`)	call `await ctx.elicit(message=..., schema=...)`
Roots (client filesystem)	supply allowed `roots` when creating session	use `context.session.list_roots()` to inspect allowed paths

Notes:

In the table, any examples like {"name":"value"} or flight://status/ID are safe to use as literal examples inside backticks.
Use streaming transports (e.g., streamable-http) when you need real-time progress, elicitation, or streaming responses.

Summary

The MCP server defines tools, resources, and prompts and can request client-side actions (sampling, elicitation).
The client connects via a session, discovers capabilities, invokes tools, reads resources, and obtains prompts.
Contexts let servers stream info, progress, and debug messages to clients during execution.
Roots let clients limit which local folders the server can access.
Sampling delegates LLM calls to the client, enabling clients to control model choice, token limits, and costs.
Elicitation allows servers to request structured input from end users via the client.

Links and references

In the next lesson we’ll explore AI Agents in action and build a custom agent using LangGraph.

Model Context Protocol (MCP)

Building an MCP Client

Example MCP configuration

Overview: Server and Client roles

Server (FastMCP) — minimal example

Client (ClientSession) — minimal example

Contexts — server-to-client progress & logging

Roots — controlled client filesystem access

Sampling — client-driven LLM calls

Elicitation — prompt end users for structured input

Feature quick-reference

Summary

Links and references

Watch Video

Practice Lab

​Example MCP configuration

​Overview: Server and Client roles

​Server (FastMCP) — minimal example

​Client (ClientSession) — minimal example

​Contexts — server-to-client progress & logging

​Roots — controlled client filesystem access

​Sampling — client-driven LLM calls

​Elicitation — prompt end users for structured input

​Feature quick-reference

​Summary

​Links and references

Watch Video

Practice Lab

Example MCP configuration

Overview: Server and Client roles

Server (FastMCP) — minimal example

Client (ClientSession) — minimal example

Contexts — server-to-client progress & logging

Roots — controlled client filesystem access

Sampling — client-driven LLM calls

Elicitation — prompt end users for structured input

Feature quick-reference

Summary

Links and references