Getting Started with MCP

This guide walks you through connecting to an MCP server, discovering its tools, and using them in an agent.

Prerequisites

An MCP server to connect to (we’ll use the filesystem server from npm)
Node.js installed (for npx)

Step 1: Define the Server

Create a configuration for the MCP server:

from definable.mcp import MCPConfig, MCPServerConfig

config = MCPConfig(servers=[
    MCPServerConfig(
        name="filesystem",
        transport="stdio",
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    ),
])

Step 2: Create the Toolkit

Wrap the configuration in an MCPToolkit:

from definable.mcp import MCPToolkit

toolkit = MCPToolkit(config=config)

Step 3: Connect and Use

Use the toolkit as a context manager to manage the server connection lifecycle:

from definable.agent import Agent
from definable.model import OpenAIChat

async with toolkit:
    # Inspect available tools
    for t in toolkit.tools:
        print(f"  {t.name}: {t.description}")

    # Create an agent with MCP tools
    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        toolkits=[toolkit],
        instructions="You can read and write files. Help the user with file operations.",
    )

    output = await agent.arun("Create a file called hello.txt with 'Hello, MCP!' in /tmp")
    print(output.content)

Complete Example

import asyncio
from definable.agent import Agent
from definable.mcp import MCPToolkit, MCPConfig, MCPServerConfig
from definable.model import OpenAIChat

async def main():
    config = MCPConfig(servers=[
        MCPServerConfig(
            name="filesystem",
            transport="stdio",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
        ),
    ])

    async with MCPToolkit(config=config) as toolkit:
        agent = Agent(
            model=OpenAIChat(id="gpt-4o"),
            toolkits=[toolkit],
        )
        output = await agent.arun("List the files in /tmp and tell me what's there.")
        print(output.content)

asyncio.run(main())

Using SSE or HTTP Transports

For remote servers, use SSE or HTTP:

MCPServerConfig(
    name="remote",
    transport="sse",
    url="https://mcp-server.example.com/sse",
)

MCPServerConfig(
    name="remote",
    transport="http",
    url="https://mcp-server.example.com/mcp",
)

Sync Usage

If you’re not in an async context, use the sync wrappers:

with MCPToolkit(config=config) as toolkit:
    agent = Agent(model=OpenAIChat(id="gpt-4o"), toolkits=[toolkit])
    output = agent.run("List files in /tmp")
    print(output.content)

Next Steps

Configuration — Timeouts, headers, tool filtering
Resources — Read data from MCP servers
Prompts — Use prompt templates

Get Started

Basics

Capabilities

Advanced

Getting Started with MCP

Prerequisites

Step 1: Define the Server

Step 2: Create the Toolkit

Step 3: Connect and Use

Complete Example

Using SSE or HTTP Transports

Sync Usage

Next Steps

​Prerequisites

​Step 1: Define the Server

​Step 2: Create the Toolkit

​Step 3: Connect and Use

​Complete Example

​Using SSE or HTTP Transports

​Sync Usage

​Next Steps

Prerequisites

Step 1: Define the Server

Step 2: Create the Toolkit

Step 3: Connect and Use

Complete Example

Using SSE or HTTP Transports

Sync Usage

Next Steps