Tutorials - Archestra Beginner Goldmine

Tutorial 1: Build Your First MCP Tool

⏱️ Time: 15 minutes • 🎯 Level: Beginner

💡 What You'll Build: A simple "calculator" tool that can perform basic math operations and be called by an AI agent.

Step 1: Create Project Structure

First, create a new directory and initialize a Node.js project:

mkdir my-first-mcp-tool
cd my-first-mcp-tool
npm init -y
npm install @modelcontextprotocol/sdk

Step 2: Create the MCP Server

Create a file called server.js:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { 
  ListToolsRequestSchema,
  CallToolRequestSchema 
} from "@modelcontextprotocol/sdk/types.js";

// Create the MCP server
const server = new Server({
  name: "calculator-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// Handle tools/list request
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "calculate",
        description: "Perform basic math operations",
        inputSchema: {
          type: "object",
          properties: {
            operation: {
              type: "string",
              enum: ["add", "subtract", "multiply", "divide"],
              description: "The math operation to perform"
            },
            a: {
              type: "number",
              description: "First number"
            },
            b: {
              type: "number",
              description: "Second number"
            }
          },
          required: ["operation", "a", "b"]
        }
      }
    ]
  };
});

// Handle tools/call request
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "calculate") {
    const { operation, a, b } = args;
    let result;

    switch (operation) {
      case "add":
        result = a + b;
        break;
      case "subtract":
        result = a - b;
        break;
      case "multiply":
        result = a * b;
        break;
      case "divide":
        if (b === 0) {
          throw new Error("Cannot divide by zero");
        }
        result = a / b;
        break;
      default:
        throw new Error(`Unknown operation: ${operation}`);
    }

    return {
      content: [
        {
          type: "text",
          text: `Result: ${result}`
        }
      ]
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Calculator MCP server running");

Step 3: Update package.json

Add the ES module type to your package.json:

{
  "name": "my-first-mcp-tool",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0"
  }
}

Step 4: Test Your Tool

Run the server and test it:

npm start

✅ Success! You've created your first MCP tool! The calculator server is now ready to be used by an AI agent.

Tutorial 2: Connect MCP Server to Gateway

⏱️ Time: 10 minutes • 🎯 Level: Beginner

💡 What You'll Learn: How to register your MCP server with the Archestra gateway so agents can discover and use it.

Step 1: Create HTTP Server Wrapper

Update your server to expose HTTP endpoints:

import express from "express";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";

const app = express();
const PORT = 3000;

// Create MCP server (same as before)
const mcpServer = new Server({
  name: "calculator-server",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

// ... (add tool handlers here)

// SSE endpoint for MCP
app.get("/mcp/sse", async (req, res) => {
  const transport = new SSEServerTransport("/mcp/message", res);
  await mcpServer.connect(transport);
});

app.post("/mcp/message", async (req, res) => {
  // Handle incoming messages
});

app.listen(PORT, () => {
  console.log(`MCP server running on http://localhost:${PORT}`);
});

Step 2: Configure Gateway

Create a gateway.config.json file:

{
  "gateway": {
    "port": 8080,
    "host": "localhost"
  },
  "mcpServers": [
    {
      "name": "calculator",
      "url": "http://localhost:3000/mcp",
      "enabled": true,
      "description": "Basic calculator tool"
    }
  ]
}

Step 3: Start Gateway

archestra gateway start --config gateway.config.json

Step 4: Verify Connection

Test that the gateway can reach your MCP server:

curl http://localhost:8080/tools/list

✅ Connected! Your MCP server is now accessible through the gateway.

Tutorial 3: Attach Tool to AI Agent

⏱️ Time: 15 minutes • 🎯 Level: Intermediate

💡 What You'll Learn: How to create an AI agent that can discover and use your calculator tool.

Step 1: Create Agent Configuration

Create agent.config.json:

{
  "agent": {
    "name": "math-assistant",
    "model": "gpt-4",
    "systemPrompt": "You are a helpful math assistant. Use the calculator tool when users ask math questions."
  },
  "gateway": {
    "url": "http://localhost:8080"
  },
  "tools": {
    "auto-discover": true,
    "allowed": ["calculate"]
  }
}

Step 2: Create Agent Script

Create agent.js:

import { Agent } from "@archestra/sdk";

const agent = new Agent({
  name: "math-assistant",
  gatewayUrl: "http://localhost:8080",
  model: "gpt-4"
});

// Initialize and connect to gateway
await agent.connect();

// Chat with the agent
const response = await agent.chat("What is 567 multiplied by 89?");
console.log(response);

// The agent will automatically:
// 1. Discover the calculator tool from the gateway
// 2. Decide to use it for math
// 3. Call calculate with operation=multiply, a=567, b=89
// 4. Return the result to the user

Step 3: Run the Agent

node agent.js

✅ Working! Your agent can now use your calculator tool automatically!

Tutorial 4: Debug Tool Invocation Failures

⏱️ Time: 20 minutes • 🎯 Level: Intermediate

💡 What You'll Learn: How to debug common issues when tools don't work as expected.

Step 1: Enable Debug Logging

Add logging to your MCP server:

// Add this to your server.js
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  console.error(`[DEBUG] Tool called: ${request.params.name}`);
  console.error(`[DEBUG] Arguments:`, JSON.stringify(request.params.arguments, null, 2));

  try {
    // Your tool logic here
    const result = executeTool(request.params);
    console.error(`[DEBUG] Success:`, result);
    return result;
  } catch (error) {
    console.error(`[DEBUG] Error:`, error.message);
    throw error;
  }
});

Step 2: Check Tool Schema Validation

Ensure your tool arguments match the schema:

// Bad: Missing required field
{
  "operation": "add",
  "a": 5
  // Missing "b" - will fail!
}

// Good: All required fields present
{
  "operation": "add",
  "a": 5,
  "b": 3
}

Step 3: Test Tool Directly

Use curl to test your tool without the agent:

curl -X POST http://localhost:3000/mcp/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "calculate",
      "arguments": {
        "operation": "add",
        "a": 5,
        "b": 3
      }
    },
    "id": 1
  }'

Step 4: Monitor Gateway Logs

Check gateway logs for routing issues:

archestra gateway logs --follow

⚠️ Common Issues:

Tool not registered in tools/list
Schema validation failures
Gateway can't reach MCP server
Incorrect tool name in agent call

✅ Debug Complete! You now know how to troubleshoot tool invocation issues systematically.

🧪 Step-by-Step Tutorials