Skip to main content

MCP (Model Context Protocol) Server

The AIDA Platform provides a Model Context Protocol (MCP) server that exposes the AI assistant as a standardized interface for AI clients and applications. MCP is an open standard that facilitates seamless integration between AI systems and external tools.

Overview​

The MCP server allows you to:

  • Access the AIDA assistant through a standardized protocol
  • Use the assistant in AI applications and workflows
  • Integrate with MCP-compatible clients (Claude Desktop, custom applications, etc.)
  • Leverage the multi-agent system through tool calls

Base URL​

  • Development: http://localhost:8000/api/assistant/mcp
  • Production: https://api.aida-platform.com/api/assistant/mcp

Authentication​

The MCP server uses API key authentication. You can create API keys in the AIDA app:

  1. Log in to the AIDA app
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Copy and save your API key (it's only shown once!)

For detailed instructions with screenshots, see the API Keys Documentation.

Using API Keys​

Include your API key in the X-API-Key header:

curl -X POST http://localhost:8000/api/assistant/mcp \
  -H "X-API-Key: aida_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Available Tools​

The MCP server exposes four main tools:

1. chat​

Send a message to the AIDA assistant. The assistant uses a multi-agent system to handle queries about energy, comfort, maintenance, and site assets.

Input Schema:

{
  "message": "string (required)",
  "sessionId": "string (optional)",
  "context": {
    "userId": "string",
    "userRole": "string",
    "siteId": "string"
  },
  "useSSE": "boolean (optional)"
}

Example:

{
  "method": "tools/call",
  "tool": "chat",
  "arguments": {
    "message": "What is my energy usage?",
    "sessionId": "my-session-123",
    "context": {
      "userId": "user-123",
      "userRole": "user"
    }
  }
}

2. query​

Query the assistant for specific information about energy, occupancy, devices, automation, or reports.

Input Schema:

{
  "query": "string (required)",
  "dataType": "energy | occupancy | devices | automation | reports (optional)",
  "timeRange": {
    "start": "ISO 8601 date-time",
    "end": "ISO 8601 date-time"
  },
  "context": "object (optional)"
}

Example:

{
  "method": "tools/call",
  "tool": "query",
  "arguments": {
    "query": "What devices are in my system?",
    "dataType": "devices"
  }
}

3. optimize​

Request AI optimization recommendations for energy usage, comfort, cost, or efficiency.

Input Schema:

{
  "target": "energy_usage | comfort | cost | efficiency (required)",
  "constraints": "object (optional)",
  "timeRange": {
    "start": "ISO 8601 date-time",
    "end": "ISO 8601 date-time"
  },
  "context": "object (optional)"
}

Example:

{
  "method": "tools/call",
  "tool": "optimize",
  "arguments": {
    "target": "energy_usage",
    "constraints": {
      "maxComfort": 0.8
    }
  }
}

4. get_status​

Get the status and capabilities of the AIDA assistant system.

Input Schema:

{}

Example:

{
  "method": "tools/call",
  "tool": "get_status",
  "arguments": {}
}

MCP Methods​

List Tools​

Get all available tools:

POST /api/assistant/mcp
Content-Type: application/json
X-API-Key: aida_your_api_key_here

{
  "method": "tools/list"
}

Response:

{
  "tools": [
    {
      "name": "chat",
      "description": "Send a message to the AIDA assistant...",
      "inputSchema": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The user's message to the assistant"
          }
        },
        "required": ["message"]
      }
    }
    // ... other tools
  ]
}

Call Tool​

Execute a tool with arguments:

POST /api/assistant/mcp
Content-Type: application/json
X-API-Key: aida_your_api_key_here

{
  "method": "tools/call",
  "tool": "chat",
  "arguments": {
    "message": "What is my energy usage?",
    "sessionId": "my-session-123"
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "Your energy usage response..."
    }
  ],
  "metadata": {
    "agent": "energyAgent",
    "statusUpdates": [
      {
        "stage": "thinking",
        "agent": null,
        "message": "Assistant Thinking...",
        "timestamp": "2025-12-11T16:57:39.139Z"
      }
    ],
    "sessionId": "my-session-123"
  }
}

Response Format​

All MCP responses follow this structure:

{
  "content": [
    {
      "type": "text",
      "text": "Response text here"
    }
  ],
  "metadata": {
    "agent": "string",
    "statusUpdates": [],
    "sessionId": "string"
  }
}

Content Types​

  • text: Plain text response from the assistant
  • json: Structured JSON data (when applicable)

Metadata​

  • agent: The agent that handled the request (e.g., "energyAgent", "siteAssetAgent")
  • statusUpdates: Array of status updates showing the processing stages
  • sessionId: Session identifier for conversation continuity

Conversation Continuity​

The MCP server maintains conversation history per session. Use the same sessionId across multiple requests to maintain context:

# First message
{
  "method": "tools/call",
  "tool": "chat",
  "arguments": {
    "message": "My name is John",
    "sessionId": "session-123"
  }
}

# Follow-up message (assistant remembers context)
{
  "method": "tools/call",
  "tool": "chat",
  "arguments": {
    "message": "What is my name?",
    "sessionId": "session-123"
  }
}

Multi-Agent System​

The AIDA assistant uses a multi-agent architecture:

  • User Assistant Agent: Routes requests to specialized agents
  • Site Asset Agent: Handles queries about buildings, floors, zones, and devices
  • Energy Savings Agent: Provides energy usage analysis and optimization
  • Comfort Agent: Manages HVAC and comfort settings
  • Maintenance Agent: Handles maintenance queries and alerts

The system automatically selects the appropriate agent based on your query.

Rate Limiting​

MCP requests are subject to rate limiting:

  • Default: 100 requests per 15 minutes per API key
  • Custom Limits: Can be set when creating API keys
  • Headers: Rate limit information is included in response headers:
    • X-RateLimit-Limit: Maximum requests allowed
    • X-RateLimit-Remaining: Remaining requests in current window
    • X-RateLimit-Reset: When the rate limit resets (ISO timestamp)

Error Handling​

Standard Error Response​

{
  "error": "Error message",
  "details": "Additional error details"
}

Common Error Codes​

  • 400 - Bad Request (invalid method or arguments)
  • 401 - Unauthorized (invalid or missing API key)
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error

Python Example​

import requests

# MCP Client
class AidaMCPClient:
    def __init__(self, api_key, base_url="http://localhost:8000"):
        self.api_key = api_key
        self.base_url = base_url.rstrip('/')
        self.session_id = f"session-{os.getpid()}"
    
    def _request(self, method, tool=None, arguments=None):
        url = f"{self.base_url}/api/assistant/mcp"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }
        
        payload = {"method": method}
        if tool:
            payload["tool"] = tool
        if arguments:
            payload["arguments"] = arguments
        
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
        return response.json()
    
    def list_tools(self):
        return self._request("tools/list")
    
    def chat(self, message, session_id=None):
        return self._request(
            "tools/call",
            tool="chat",
            arguments={
                "message": message,
                "sessionId": session_id or self.session_id
            }
        )

# Usage
client = AidaMCPClient(api_key="aida_your_key_here")
tools = client.list_tools()
response = client.chat("What is my energy usage?")
print(response["content"][0]["text"])

JavaScript/TypeScript Example​

class AidaMCPClient {
  constructor(
    private apiKey: string,
    private baseUrl: string = "http://localhost:8000"
  ) {}

  private async request(method: string, tool?: string, arguments?: any) {
    const response = await fetch(`${this.baseUrl}/api/assistant/mcp`, {
      method: "POST",
      headers: {
        "X-API-Key": this.apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        method,
        tool,
        arguments,
      }),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return response.json();
  }

  async listTools() {
    return this.request("tools/list");
  }

  async chat(message: string, sessionId?: string) {
    return this.request("tools/call", "chat", {
      message,
      sessionId: sessionId || `session-${Date.now()}`,
    });
  }
}

// Usage
const client = new AidaMCPClient("aida_your_key_here");
const tools = await client.listTools();
const response = await client.chat("What is my energy usage?");
console.log(response.content[0].text);

Testing​

Use our test script to verify your MCP integration:

cd test
python3 test_mcp_server.py --api-key aida_your_key_here

Or use the interactive mode:

python3 test_mcp_server.py --api-key aida_your_key_here --interactive

See the test documentation for more details.

Best Practices​

  1. Session Management: Use consistent session IDs for conversation continuity
  2. Error Handling: Always check for errors in responses
  3. Rate Limiting: Monitor rate limit headers and implement backoff strategies
  4. API Key Security: Never expose API keys in client-side code
  5. Context: Provide user context when available for better responses

Integration with Claude Desktop​

To use AIDA MCP with Claude Desktop, add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "aida": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "-H", "X-API-Key: YOUR_API_KEY",
        "-H", "Content-Type: application/json",
        "-d", "@-",
        "http://localhost:8000/api/assistant/mcp"
      ]
    }
  }
}

Next Steps​

Ready to integrate? Create an API key in the AIDA app and start using the MCP server to access the AI assistant from your applications.