MCP Primitives

MCP (Model Context Protocol) primitives are standardized building blocks that enable agents to access structured data and functionality from MCP servers. This guide shows you how to use all MCP primitives: tools, resources, prompts, roots, and elicitation.

What are MCP Primitives?

Tools

Functions that interact with external systems, such as querying databases, calling APIs, or performing computations

Resources

Data (files, database schemas, application-specific information) exposed by MCP servers, accessible via URIs

Prompts

Reusable messages and instructions that can be listed and invoked from MCP servers with parameters

Roots

File system paths that MCP servers make accessible for browsing and operations

Elicitation

Interactive input requests that allow servers to ask for structured user input during tool execution

Sampling

Server-side LLM invocation capability for specialized reasoning (coming soon)

Transport Types

mcp-agent supports all MCP transport types:

Creating an MCP Server

First, create an MCP server that exposes resources and prompts:
from mcp.server.fastmcp import FastMCP
import datetime
import json

mcp = FastMCP("Resource Demo MCP Server")

@mcp.resource("demo://docs/readme")
def get_readme():
    """Provide the README file content."""
    return "# Demo Resource Server\n\nThis is a sample README resource."

@mcp.prompt()
def echo(message: str) -> str:
    """Echo the provided message.
    
    This is a simple prompt that echoes back the input message.
    """
    return f"Prompt: {message}"

if __name__ == "__main__":
    mcp.run()

Agent Configuration

Configure your agent to connect to the MCP server:
$schema: ../../../schema/mcp-agent.config.schema.json

execution_engine: asyncio
logger:
  transports: [console, file]
  level: debug
  progress_display: true

mcp:
  servers:
    demo_server:
      command: "uv"
      args: ["run", "demo_server.py"]
      description: "Demo MCP server for resources and prompts"

openai:
  default_model: "gpt-4o-mini"

Using MCP Primitives in Your Agent

Here’s how to use MCP primitives in your agent application:
import asyncio
from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="mcp_basic_agent")

async def example_usage():
    async with app.run() as agent_app:
        logger = agent_app.logger
        
        # Create an agent connected to the demo server
        agent = Agent(
            name="agent",
            instruction="Demo agent for MCP resource and prompt primitives",
            server_names=["demo_server"],
        )

        async with agent:
            # List all available resources
            resources = await agent.list_resources("demo_server")
            logger.info("Available resources:", data=resources.model_dump())

            # List all available prompts
            prompts = await agent.list_prompts("demo_server")
            logger.info("Available prompts:", data=prompts.model_dump())

            # Get both resource and prompt in a single call
            combined_messages = await agent.create_prompt(
                prompt_name="echo",
                arguments={"message": "My name is John Doe."},
                resource_uris="demo://docs/readme",
                server_names=["demo_server"],
            )

            # Use LLM to process the content
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            res = await llm.generate_str([
                "Summarise what are my prompts and resources?",
                *combined_messages,
            ])
            logger.info(f"Summary: {res}")

if __name__ == "__main__":
    asyncio.run(example_usage())

Key Methods

Listing Primitives

# List all resources from a server
resources = await agent.list_resources("demo_server")

# List all prompts from a server  
prompts = await agent.list_prompts("demo_server")

# List all tools from a server
tools = await agent.list_tools("demo_server")

Using Prompts and Resources

# Create prompt message with prompt only
prompt_messages = await agent.create_prompt(
    prompt_name="echo",
    arguments={"message": "Hello, world!"},
    server_names=["demo_server"]
)

# Create prompt messages with prompts and resources
combined_messages = await agent.create_prompt(
    prompt_name="echo",
    arguments={"message": "My name is John Doe."},
    resource_uris="demo://docs/readme",
    server_names=["demo_server"]
)

Elicitation Support

Elicitation allows MCP servers to request additional structured input from users during tool execution:
from mcp.server.fastmcp import FastMCP, Context
from mcp.server.elicitation import (
    AcceptedElicitation,
    DeclinedElicitation,
    CancelledElicitation,
)
from pydantic import BaseModel, Field

mcp = FastMCP("Interactive Server")

@mcp.tool()
async def deploy_application(
    app_name: str,
    environment: str,
    ctx: Context
) -> str:
    """Deploy an application with confirmation."""
    
    # Request confirmation with structured input
    class DeploymentConfirmation(BaseModel):
        confirm: bool = Field(description="Confirm deployment?")
        notify_team: bool = Field(default=False, description="Notify team via Slack?")
        message: str = Field(default="", description="Optional deployment message")
    
    result = await ctx.elicit(
        message=f"Confirm deployment of {app_name} to {environment}?",
        schema=DeploymentConfirmation
    )
    
    match result:
        case AcceptedElicitation(data=data):
            if data.confirm:
                # Perform deployment
                if data.notify_team:
                    # Send notification with message
                    pass
                return f"Deployed {app_name} to {environment}"
            return "Deployment cancelled by user"
        case DeclinedElicitation():
            return "Deployment declined"
        case CancelledElicitation():
            return "Deployment cancelled"

Roots Support

Roots define file system paths that MCP servers make accessible:
mcp:
  servers:
    project_server:
      command: "python"
      args: ["-m", "my_mcp_server"]
      roots:
        - uri: "file:///workspace/project"
          name: "Project Root"
        - uri: "file:///shared/resources"
          name: "Shared Resources"
        - uri: "file:///tmp/scratch"
          name: "Scratch Space"

Authentication Support

mcp-agent supports authentication for MCP servers:

Primitive Support Matrix

PrimitiveSTDIOSSEWebSocketHTTPStatus
ToolsFully Supported
ResourcesFully Supported
PromptsFully Supported
RootsFully Supported
ElicitationFully Supported
Sampling🚧🚧🚧🚧Coming Soon

Complete Examples