update documentation for mcp

Author: ItsJustMeChris

astro.config.mjs

@@ -28,6 +28,7 @@ export default defineConfig({
           label: "Class Reference",
           items: [
             { label: "Loom", slug: "reference/loom" },
+            { label: "MCP", slug: "reference/mcp" },
             { label: "Agent", slug: "reference/agent" },
             { label: "Runner", slug: "reference/runner" },
             { label: "Trace", slug: "reference/trace" },

src/content/docs/index.mdx

@@ -52,6 +52,9 @@ import { Card, CardGrid } from "@astrojs/starlight/components";
     Track every step of your agent's execution with detailed, hierarchical
     traces.
   </Card>
+  <Card title="MCP Integration" icon="cloud-download">
+    Leverage third party integrations to take your agents to the next level 
+  </Card>
   <Card title="Tool Integration" icon="puzzle">
     Extend your agents with custom tools for database access, API calls, and
     more.

src/content/docs/reference/agent.mdx

@@ -37,6 +37,7 @@ interface AgentConfig {
   sub_agents?: Agent[]; // Optional: Sub-agents that can be called
   tools?: ToolCall[]; // Optional: Tools the agent can use
   model?: string; // Optional: Default is 'gpt-4o'
+  mcp_servers?: (MCPServerSSE | MCPServerStdio)[];
   web_search?: WebSearchConfig; // Optional: Web search configuration
   timeout_ms?: number; // Optional: Default is 60000ms (1 minute)
 }
@@ -88,6 +89,32 @@ const result = await agent.run(
 );
 ```
 
+## Working with MCP Servers
+
+Loom supports integrating with external tools using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), a standard that allows third-party applications and services to provide context and capabilities to LLMs.
+
+You can use two types of MCP connections:
+
+- [`MCPServerSSE`](../reference/mcp) – Connects to an MCP tool server over **Server-Sent Events**
+- [`MCPServerStdio`](../reference/mcp) – Connects to a local MCP tool server via **stdio**
+
+### Example: Connecting to MCP Servers
+
+```ts
+import { Agent, MCPServerSSE, MCPServerStdio } from "loom-agents";
+
+const researchAgent = new Agent({
+  name: "MCP Tool Runner",
+  purpose: "Run a connected MCP tool!",
+  mcp_servers: [
+    new MCPServerSSE(new URL("http://localhost:3001/sse")),
+    new MCPServerStdio("bun", ["stdio.ts"]),
+  ],
+});
+```
+
+With this configuration, your agent can call tools exposed by the connected MCP servers seamlessly.
+
 ## Defining Tools
 
 Tools allow agents to interact with external systems or perform specialized tasks:

src/content/docs/reference/mcp.mdx

@@ -0,0 +1,121 @@
+---
+title: MCPServer  
+description: Base class for connecting to Model Context Protocol-compatible tool servers over SSE or stdio
+---
+
+The `MCPServer` system provides a standardized way to connect to tool servers that implement the [Model Context Protocol (MCP)](https://modelcontext.org). It supports both **SSE (Server-Sent Events)** and **stdio (standard input/output)** transports.
+
+## Creating a Server Connection
+
+There are two built-in classes for connection:
+
+- `MCPServerSSE`: Connects to a remote MCP server using Server-Sent Events.
+- `MCPServerStdio`: Launches and communicates with a local MCP server using standard input/output.
+
+```ts
+import { MCPServerSSE, MCPServerStdio } from "loom-agents/mcp";
+
+// Using SSE
+const mcpSSE = new MCPServerSSE(new URL("http://localhost:3000/mcp"));
+
+// Using stdio
+const mcpStdio = new MCPServerStdio("node", ["./tool-server.js"]);
+```
+
+## Listing Available Tools
+
+Each server may expose a set of tools that can be queried:
+
+```ts
+const tools = await mcpSSE.getTools();
+console.log(tools);
+// {
+//   tools: [
+//     {
+//       name: "calculate-bmi",
+//       inputSchema: {
+//         type: "object",
+//         properties: [Object],
+//         required: [Array],
+//         additionalProperties: false,
+//         $schema: "http://json-schema.org/draft-07/schema#",
+//       },
+//     },
+//     {
+//       name: "fetch-weather",
+//       inputSchema: {
+//         type: "object",
+//         properties: [Object],
+//         required: [Array],
+//         additionalProperties: false,
+//         $schema: "http://json-schema.org/draft-07/schema#",
+//       },
+//     },
+//   ];
+// }
+```
+
+This will automatically connect the client if it hasn’t already.
+
+## Calling a Tool
+
+Once connected, tools can be called directly by name:
+
+```ts
+const result = await mcpSSE.callTool({
+  name: "calculate-bmi",
+  arguments: {
+    "weightKg":70,
+    "heightM":1.75
+  }
+});
+
+console.log(result);
+// {
+//   content: [
+//     {
+//       type: "text",
+//       text: "22.857142857142858",
+//     },
+//   ];
+// }
+
+// Note, Loom parses MCP results for errors and sends the content / output off `.content`
+// [
+//  {
+//    type: "text",
+//    text: "22.857142857142858",
+//  },
+//]
+```
+
+## Extending MCPServer
+
+If you want to implement a custom transport or extend tool behaviors, you can subclass `MCPServerBase`.
+
+```ts
+class CustomMCPServer extends MCPServerBase {
+  constructor(myTransport: CustomTransport) {
+    super(myTransport);
+  }
+
+  // Custom behavior
+}
+```
+
+## Internals
+
+The `MCPServerBase` manages client connection state and handles listing and calling tools. It lazily initializes the client only when needed:
+
+```ts
+await this.client.connect(this.transport);
+```
+
+It caches tool metadata after the first call to `getTools()` to avoid redundant lookups.
+
+## Related
+
+- [Agent](/docs/reference/agent): Interacts with tools through an MCPServer
+- [Tool Definition](/docs/reference/tool): Learn how tools are defined and exposed
+- [Trace](/docs/reference/trace): Structured tracking of tool calls and agent interactions
+- [Loom Configuration](/docs/reference/loom): Customize global AI behavior and context handling