Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.definable.ai/llms.txt

Use this file to discover all available pages before exploring further.

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",
)

​
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