MCP Connection & Configuration

How to connect to and configure the Guid AI MCP service

This document describes how to connect to and configure the Guid AI MCP service.

Prerequisites

A valid API Key (sk-xxx)
The gateway is deployed and exposes the /mcp endpoint
The client supports MCP Streamable HTTP

Client configuration

Add the following to your MCP config:

{
  "mcpServers": {
    "guid": {
      "url": "https://www.guid.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk-xxx"
      }
    }
  }
}

Field	Description
`mcpServers.guid`	Service key name; recommended value is `guid`
`url`	Gateway address + `/mcp`; must share the same origin as the API Base URL
`headers.Authorization`	`Bearer` + your API Key

Replace sk-xxx with your API Key.

Session management

MCP Streamable HTTP uses sessions:

Item	Description
First request	Server returns `Mcp-Session-Id` in the response headers
Subsequent requests	Client must send the same `Mcp-Session-Id` in request headers
End session	`DELETE /mcp`

Client SDKs usually manage sessions automatically.

Authentication

Auth is identical to the V1 API
Shares the same API Key billing, limits, and model restrictions
Admins may append -{channelId} after the Key to select a channel (e.g. sk-xxx-6)

Auth failures return HTTP 401 / 403.

Verify the connection

After configuration, verify via the MCP protocol:

Call tools/list and confirm Tools such as list_models and generate_image are returned
Call list_models and confirm returned models include supported_endpoint_types

If the Tool list is empty or missing expected Tools, check:

Whether the API Key is valid and the balance is sufficient
Whether the token restricts available models
Whether models support the corresponding supported_endpoint_types

Troubleshooting

Symptom	Likely cause	Action
Connection failed	Wrong URL or gateway not running	Check Base URL and `/mcp` reachability
401 / 403	Invalid Key or IP not on allowlist	Check token settings
Tool list missing image/video	No permission for those models	Call `list_models` and check `supported_endpoint_types`
Video stuck in queued	Upstream queue	Poll at `next_poll_after_sec` intervals; avoid overly frequent requests
TTS returns an error	Invalid voice	Call `list_audio_voices` first to get the correct `code`

Quick Start

Audio API

Text-to-speech (TTS) and voice list queries

Skills

Install the guid-ai-skills package to call multimodal generation from Agent conversations