MCPs Guide

Model Context Protocol (MCP) connections let agents call external services while keeping credentials and transport details centralized. Use this guide when you need to create, manage, or validate MCP configurations across REST, the Python SDK, and the CLI.

Compare REST, SDK, and CLI support in the AIP capability matrix.

aip mcps commands accept either the MCP ID or a unique name. If multiple connections share similar names, prefer the explicit ID in scripts to avoid updating the wrong record.

Create an MCP Configuration

When to use: Establish a new integration endpoint or clone settings from staging to production.

Python SDK

from glaip_sdk import Client

client = Client()

mcp = client.mcps.create_mcp(
    name="weather-service",
    description="HTTP weather API via MCP",
    transport="http",
    config={"url": "https://weather.example.com/mcp"},
    authentication={
        "type": "api-key",
        "key": "X-API-Key",
        "value": "secret-key",
    },
)
print(mcp.id)

CLI

CLI (Import file)

REST

Using files with the CLI

• Inline vs file inputs: Any JSON flag (e.g., --config, --auth) accepts either inline JSON or a file reference using @path/to/file.json. File inputs are parsed with the same validation as inline payloads.

• Importing full definitions: Supply --import <file> to recreate an MCP from an export. The CLI loads every supported field from the file (name, transport, config, authentication, mcp_metadata, etc.).

• Flag overrides: CLI flags provided alongside --import override the matching keys in the file. Leaving a flag out keeps the file’s value. When the file already contains required fields like name and transport, those flags become optional.

Example config file:

{
  "url": "https://weather.example.com/mcp"
}

Example auth file:

{
  "type": "api-key",
  "key": "X-API-Key",
  "value": "secret-key"
}

Example import file:

{
  "name": "weather-service",
  "transport": "http",
  "description": "HTTP weather API via MCP",
  "config": {
    "url": "https://weather.example.com/mcp"
  },
  "authentication": {
    "type": "api-key",
    "headers": {
      "X-API-Key": "secret-key"
    }
  },
  "mcp_metadata": {
    "environment": "staging",
    "owner": "platform-team"
  }
}

Command examples:

# Use dedicated config/auth files with @file syntax
aip mcps create \
  --name weather-service \
  --transport http \
  --config @weather-config.json \
  --auth @weather-auth.json

# Import and override selected fields
aip mcps create \
  --import weather-mcp.json \
  --name weather-service-prod \
  --transport http

Rotate Credentials or Update Configs

When to use: Refresh secrets before they expire or tweak transport parameters without downtime.

Python SDK

client.mcps.update_mcp(
    mcp.id,
    authentication={
        "type": "api-key",
        "key": "X-API-Key",
        "value": "new-secret",
    },
)

CLI

REST

Validate Connections Before Saving

When to use: Confirm the connector responds and auth works before exposing it to agents.

Test connectivity without persisting a record:

curl -X POST "$AIP_API_URL/mcps/connect" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AIP_API_KEY" \
  -d '{
        "transport": "http",
        "config": {"url": "https://weather.example.com/mcp"},
        "authentication": {
          "type": "api-key",
          "key": "X-API-Key",
          "value": "secret-key"
        }
      }'

# CLI helper (uses the same endpoint)
aip mcps connect --from-file weather-mcp.json

Common errors and fixes

Symptom	Likely cause	Fix
401 Unauthorized when validating	API key lacks MCP permissions or connector secrets expired.	Issue a runner/creator key or rotate the provider secret under Rotate Credentials.
404 or connection refused during validation	Base URL incorrect or firewall blocking outbound traffic.	Confirm the URL, allowlist the host, or test from a network that can reach the provider.
Connector saves but tools list is empty	Provider exposes no MCP tools or scope is limited.	Run discovery with elevated scopes or confirm the provider exports MCP metadata.
Agents timeout when calling the MCP	Runtime overrides missing, or concurrency exceeds provider limits.	Use per-run overrides for busy periods and tune agent timeout settings.

Discover MCP Tools

When to use: Inspect which tool definitions become available once the connector is active.

curl -sL "$AIP_API_URL/mcps/$MCP_ID/tools" -H "X-API-Key: $AIP_API_KEY" | jq

Attach discovered tool IDs to agents just like native or custom uploads.

Runtime Overrides During Agent Runs

When to use: Supply per-run credentials or endpoints that differ from the stored defaults.

client.agents.run_agent(
    agent_id,
    "Summarise sales data",
    runtime_config={
        "mcp_configs": {
            "weather-service": {
                "authentication": {
                    "type": "api-key",
                    "key": "X-API-Key",
                    "value": "temporary-override"
                }
            }
        }
    }
)

Runtime overrides are processed in-memory for the run and do not modify stored MCP records. CLI support is under development; use the SDK or REST API for now.

MCP Maintenance

When to use: Audit or retire connectors after incidents, vendor changes, or environment migrations.

• Soft delete via DELETE /mcps/{id}.

• List MCPs with GET /mcps or aip mcps list.

• Combine MCP tooling with the Tools guide when you want to import remote tools into agent definitions.

Best Practices

When to use: Align your organisation on safe defaults that reduce downtime and credential leaks.

1

Store secrets securely

Use environment variables when invoking CLI or REST workflows; avoid committing secrets to JSON.

2

Validate before saving

Run aip mcps connect --from-file ... or /mcps/connect to catch network or auth issues early.

3

Document tool discovery

Record which MCP tool IDs power each agent so teammates can maintain the integration.

4

Monitor timeouts

Many services expose their own rate or timeout limits; set config.timeout accordingly and surface errors in run logs.

Related Documentation

• Tools guide — attach native, custom, and MCP-discovered tools.

• Agents guide — manage agent lifecycle and runtime overrides.

• Automation & scripting — script MCP promotion in CI pipelines.