Developers/MCP Integration

hubMCP Protocol v1.0

Connect Everything.

Model Context Protocol (MCP) integration lets your bots connect to any tool, API, or data source. Give your AI agents real-time access to calendars, databases, ticketing systems, and more — all from inside your universe.

View MCP Serversarrow_forward codeBot Scripting Guide

mcp-config.json

"mcpServers": {
  "calendar": {
    "url": "https://mcp.bawes.io/calendar",
    "tools": ["list_events", "create_event"]
  },
  "ticketing": {
    "url": "https://mcp.bawes.io/jira",
    "tools": ["search_issues", "create_ticket"]
  }
}

hub

How MCP Works

Bots discover and call tools via the Model Context Protocol over HTTP.

1. Discover Tools

On startup and every hour, the bot calls tools/list on each MCP server to discover available capabilities.

psychology

2. AI Chooses

During conversation, the AI model selects the right tool based on the player's request and the tool's schema.

call_made

3. Execute & Respond

The bot sends tools/call to the MCP server and feeds the result back to the AI for the final response.

Registering an MCP Server

In the in-game bot editor, under MCP Servers, you can add, edit, test, and remove servers. Each server requires:

badge

Name

Label for the server (e.g. “Knowledge Base”)

link

Server URL

Full URL of the MCP-over-HTTP endpoint

key

Auth Type

None, Bearer Token, or API Key (stored encrypted)

list

Headers

Optional custom headers sent with every request

check_circleTest Connection

After saving, click Test Connection to verify the tools/list response and see which tools are exposed by your server.

test-connection.http

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "test",
  "method": "tools/list"
}

Transport Contract

MCP over Streamable HTTP — the same protocol used by Claude Code and other MCP clients.

handshakeInitialize

Sent before any method call. The server can return a Mcp-Session-Id header for stateful sessions.

initialize.json

{
  "jsonrpc": "2.0",
  "id": "init",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "workadventure-mcp-bot",
      "version": "1.0.0",
      "player_id": "<player-uuid>"
    }
  }
}

calltools/call

When the AI selects a tool, the bot sends a tools/call request with the chosen arguments.

tools-call.json

{
  "jsonrpc": "2.0",
  "id": "exec",
  "method": "tools/call",
  "params": {
    "name": "my_tool",
    "arguments": {
      "query": "latest updates"
    }
  }
}

Timeout: 10 seconds. Requests exceeding this are discarded and the AI receives an error. All tool requests are sent with player_id for per-user session tracking.

Player Identification

Each player gets their own MCP session, allowing your server to distinguish users and maintain per-player state.

badge

player_id

A stable UUID sent with every initialize request. Use it for per-player state, context, and rate limits.

explore

Tool Discovery

During initial tool discovery (before any player conversation), player_id is null. Your handler must accept null.

sync_saved_locally

Session Lifecycle

Each player gets a cached MCP session keyed by server URL, auth config, and player_id. Sessions expire after 1 hour of inactivity. First tool call per player triggers one initialize round-trip (~50–200ms), then reuse within the hour.

cached

Tool List Caching

The tool list from tools/list is cached for 1 hour across all players. Tool changes may take up to 1 hour to propagate unless the bot is restarted.

session-lifecycle.ts

// Each player gets their own session
const sessions = new Map();

function getSession(playerId, serverUrl) {
  const key = `${playerId}:${serverUrl}`;
  let session = sessions.get(key);

  if (!session || isExpired(session)) {
    // Triggers initialize round-trip
    session = createSession(serverUrl);
    sessions.set(key, session);
  }

  return session;
}

// Session expires after 1h inactivity
// Tool list refreshes every 1h
setInterval(refreshToolList, 3600000);

Minimal MCP Server (Node.js)

A complete, runnable example to get started with your own MCP server.

mcp-server.js

import express from 'express';
const app = express();
app.use(express.json());

app.post('/mcp', (req, res) => {
  const { method, params } = req.body;

  if (method === 'initialize') {
    return res.json({
      jsonrpc: '2.0', id: req.body.id,
      result: { protocolVersion: '2024-11-05',
        capabilities: {},
        serverInfo: { name: 'example-mcp', version: '1.0.0' },
      },
    });
  }

  if (method === 'tools/list') {
    return res.json({
      jsonrpc: '2.0', id: req.body.id,
      result: { tools: [{
        name: 'my_query',
        description: 'Query knowledge about a topic',
        inputSchema: {
          type: 'object',
          properties: { topic: { type: 'string' } },
        },
      }]},
    });
  }

  if (method === 'tools/call') {
    const result = `You asked about: ${params.arguments.topic}`;
    return res.json({
      jsonrpc: '2.0', id: req.body.id,
      result: { content: [{ type: 'text', text: result }] },
    });
  }

  res.status(400).json({
    jsonrpc: '2.0', id: req.body.id,
    error: { code: -32601, message: 'Method not found' },
  });
});

app.listen(3001);

Related Features

handyman

Ready to connect your bots?

Give your AI agents the power to act. MCP integration unlocks a new dimension of bot capabilities.

Get Started with MCP open_in_newExplore Bot Scripting