MCP Integration

The Model Context Protocol (MCP) is an open protocol developed by Anthropic to standardize how language models interact with external systems—such as tools, memory backends, and context managers. MCP enables structured, dynamic communication between an LLM and its environment, empowering models to access external tools, retrieve real-time information, and perform complex, multi-step reasoning.

info

Standard input/output is not available in the web environment. Therefore, only the MCP tools based on streamable HTTP are available in the web environment.
For information on MCP integration in the web environment, please refer to the WebAssembly Supports.

The following examples demonstrate MCP tools that use standard input/output only in a native environment.

Step-by-Step Guide

Loading MCP Clients

You can connect to any MCP server using the MCPClient interface. For example, the snippet below connects to the official GitHub MCP server.

Python

client = await ai.MCPClient.from_stdio(
    "npx", ["-y", "@modelcontextprotocol/server-github"]
)

JavaScript

const client = await ai.MCPClient.newStdio("npx", [
  "-y",
  "@modelcontextprotocol/server-github",
]);

This launches the GitHub MCP server as a subprocess using standard I/O for communication. The agent automatically discovers the tools exposed by the server and registers them to its internal toolset.

Extracting MCP Tools

Each MCP server can expose multiple tools. To optimize context usage, you can selectively extract a subset of tools rather than registering all of them.

Python

tools = [
    client.get_tool("search_repositories"),
    client.get_tool("get_file_contents"),
]

JavaScript

const tools = [
  client.getTool("search_repositories"),
  client.getTool("get_file_contents"),
];

Registering Tools into Agent

To integrate MCP tools with LM, they must be registered to Agent.
Once registered, the agent can automatically invoke these tools during reasoning or when responding to user queries.

Python

lm = await ai.LangModel.new_local("Qwen/Qwen3-8B", progress_callback=print)
agent = ai.Agent(lm, tools)

Typescrpt

const lm = await ai.LangModel.newLocal("Qwen/Qwen3-8B", null, console.log);
const agent = new ai.Agent(lm, tools);

Querying via MCP Tools

With tools registered, the agent can automatically use them when you invoke run() or run_delta().

Python

question = "Search the repository named brekkylab/ailoy and describe what it does based on its README.md."
async for resp in agent.run(question):
    agent.print(resp)

JavaScript

const question =
  "Search the repository named brekkylab/ailoy and describe what it does based on its README.md.";
for await (const resp of agent.run(question)) {
  agent.print(resp);
}

This demonstrates how the agent leverages the GitHub MCP tools to search repositories and summarize their contents.

Complete Example

The following end-to-end example demonstrates how to set up an agent, connect to the GitHub MCP server, and issue a query.

Python

import asyncio

import ailoy as ai


async def main():
    client = await ai.MCPClient.from_stdio(
        "npx", ["-y", "@modelcontextprotocol/server-github"]
    )
    tools = [
        client.get_tool("search_repositories"),
        client.get_tool("get_file_contents"),
    ]
    lm = await ai.LangModel.new_local("Qwen/Qwen3-4B", progress_callback=print)
    agent = ai.Agent(lm, tools)
    query = "Search the repository named brekkylab/ailoy and describe what it does based on its README.md."
    async for resp in agent.run(query):
        print(resp)


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

JavaScript

import * as ai from "ailoy-node";

async function main() {
  const client = await ai.MCPClient.newStdio("npx", [
    "-y",
    "@modelcontextprotocol/server-github",
  ]);
  const tools = [
    client.getTool("search_repositories"),
    client.getTool("get_file_contents"),
  ];
  const lm = await ai.LangModel.newLocal("Qwen/Qwen3-4B", null, console.log);
  const agent = new ai.Agent(lm, tools);
  const query =
    "Search the repository named brekkylab/ailoy and describe what it does based on its README.md.";
  for await (const resp of agent.run(query)) {
    console.log(resp.message);
  }
}

main().catch((err) => {
  console.error("Error:", err);
});

Output

╭─ Tool Call: github-get_file_contents ────────────────────────────────╮
│ {                                                                    │
│   "repo": "ailoy",                                                   │
│   "path": "README.md",                                               │
│   "owner": "brekkylab",                                              │
│   "branch": "feature/add-qwen3-big-models"                           │
│ }                                                                    │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Tool Result ────────────────────────────────────────────────────────╮
│ [                                                                    │
│   "{\"name\": \"README.md\", \"path\": \"README.md\", \"sha\":       │
│ \"563dde166b65319e7614b81a9d8330eee06537d3\", \"size\": 4443,        │
│ \"url\":                                                             │
│ \"https://api.github.com/repos/brekkylab/ailoy/contents/README.md?re │
│ f=feature/add-qwen3-big-models\", \"html_url\":                      │
│ \"https://github.com/brekkylab/ailoy/blob/feature/add-qwen3-big-mode │
│ ls/README.md\", \"git_url\":                                         │
│ \"https://api.github.com/repos/brekkylab/ailoy/git/blobs/563dde166b6 │
│ 5319e7614b81a9d8330eee06537d3\", \"download_url\":                   │
│ \"https://raw.githubusercontent....(truncated)                       │
╰──────────────────────────────────────────────────────────────────────╯
The repository **brekkylab/ailoy** is a **lightweight library** for building AI applications, such as **agent systems** or **RAG (Retrieval-Augmented Generation) pipelines**. It is designed to simplify the integration and usage of AI models, allowing developers to import and use AI capabilities with minimal effort.

### Key Features:
- **Support for Local and Cloud AI Models**: It enables the use of local AI models (e.g., Qwen3 variants) and cloud APIs (e.g., OpenAI, Gemini, Claude).
- **Multi-turn Conversations**: Supports conversational agents with customizable system messages.
- **Reasoning and Tool Calling**: Facilitates reasoning-based workflows and integration with tools (including `MCP`).
- **Vector Store Support**: Built-in integration with vector databases like `Faiss` and `ChromaDB`.
- **Cross-Platform Compatibility**: Works on Windows, macOS (Apple Silicon), and Linux, with specific hardware requirements for local model execution.

### Supported Models:
- **Local Language Models**: Qwen3 variants (0.6B, 1.7B, 4B, 8B, 14B, 32B, 30B-A3B).
- **Cloud Models**: OpenAI, Gemini, and Claude.
- **Embedding Models**: BAAI/bge-m3.

### Use Cases:
- **Chatbots**: Build simple or advanced chatbots with local or cloud models.
- **RAG Pipelines**: Combine retrieval and generation for enhanced AI applications.
- **Custom AI Agents**: Create agents with reasoning capabilities and tool integration.

### Requirements:
- **Hardware**: At least 8GB of GPU memory is recommended for most models, with higher requirements for larger models like Qwen3-8B (12GB).
- **OS**: Windows, macOS (Apple Silicon), or Linux with specific versions and drivers.

### Getting Started:
- **Node.js**: Install via `npm install ailoy-node` and use TypeScript examples.
- **Python**: Install via `pip install ailoy-py` and use Python examples.

This repository is in an **early development stage**, and APIs may change. For more details, refer to the [official documentation](https://brekkylab.github.io/ailoy/).