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.

MCP Patterns

Direct MCP Definition (Recommended)

Define and attach MCPs directly to agents:

from glaip_sdk import Agent, MCP

weather_mcp = MCP(
    name="weather",
    transport="http",
    config={"url": "https://weather.example.com/mcp"},
    authentication={
        "type": "api-key",
        "key": "X-API-Key",
        "value": "secret-key",
    }
)

agent = Agent(
    name="weather-bot",
    instruction="You help users check the weather",
    mcps=[weather_mcp]
)

Conditional MCP inclusion:

from mcps import arxiv_mcp  # Only created if env vars set

agent = Agent(
    name="research-agent",
    instruction="You help with research",
    mcps=[arxiv_mcp] if arxiv_mcp else []
)

You can reference MCPs by name string or using MCP.from_native():

from glaip_sdk import Agent, MCP

# Using name string (requires deploy())
agent = Agent(name="agent", instruction="...", mcps=["weather_mcp"])
agent.deploy()

# Using MCP.from_native() (requires deploy())
weather = MCP.from_native("weather_mcp")
agent = Agent(name="agent", instruction="...", mcps=[weather])
agent.deploy()

Use this pattern for:

• Attaching MCPs to specific agents

• Conditional MCP inclusion

• Simple integrations

MCP Registry Management (Secondary)

Use the SDK Client for managing the MCP registry and cross-environment governance. This is a secondary pattern; prefer defining MCPs directly and attaching them to Agent instances for day-to-day application code.

from glaip_sdk import Client

client = Client()

# Create MCP in registry
mcp = client.mcps.create_mcp(
    name="weather-service",
    transport="http",
    config={"url": "https://weather.example.com/mcp"},
    authentication={...}
)

# List MCPs
mcps = client.mcps.list_mcps()

# Test connection from config
result = client.mcps.test_mcp_connection_from_config({
    "transport": "http",
    "config": {"url": "https://weather.example.com/mcp"}
})

Use this pattern for:

• Managing the MCP registry

• Listing and searching MCPs

• Testing MCP connections

• MCP governance across environments

---

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

CLI

Get tools from a saved MCP:

aip mcps tools <MCP_ID>

Get tools from a config file (without saving to DB):

aip mcps tools --from-config mcp-config.json

Get just tool names for allowed_tools config:

# Simple list output - easy to copy-paste
aip mcps tools <MCP_ID> --names-only

# JSON array output - ready for config files
aip mcps tools <MCP_ID> --names-only --json

Example config file (mcp-config.json):

{
  "transport": "sse",
  "config": {
    "url": "https://mcp.obrol.id/f/sse"
  }
}

Python SDK

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

Restrict Agent Tool Access (Allow List)

When to use: Limit which MCP tools an agent can access instead of allowing all tools from the MCP.

Tool names in allowed_tools must match exactly. Use Discover MCP Tools to find the correct tool names before configuring the allow list.

Configure Tool Filtering at Agent Level

Python SDK

# First, discover available tools
tools = client.mcps.get_mcp_tools(mcp_id)
print([t['name'] for t in tools])  # ['get_weather', 'get_forecast', 'get_alerts']

# Create agent with only specific tools allowed
# Note: For new code, prefer the Agent pattern (see agents-guide.md)
agent = client.agents.create_agent(
    name="Weather Agent",
    instruction="Provide weather info",
    model_name="gpt-5",
    mcps=[mcp_id],
    mcp_configs={
        mcp_id: {
            "allowed_tools": ["get_weather", "get_forecast"]  # blocks get_alerts
        }
    }
)

REST

Configuration rules:

• Omit allowed_tools or set to null or empty list [] — allows all MCP tools (default)

• Set to ["tool1", "tool2"] — allows only listed tools

Combining with authentication:

mcp_configs={
    mcp_id: {
        "allowed_tools": ["read_data"],
        "authentication": {
            "type": "bearer-token",
            "token": "agent-specific-token"
        }
    }
}

Update Existing Agent Tool Access

Python SDK

client.agents.update_agent(
    agent_id,
    mcp_configs={
        mcp_id: {
            "allowed_tools": ["get_weather", "get_forecast", "get_alerts"]  # add get_alerts
        }
    }
)

REST

Runtime Overrides During Agent Runs

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

Override authentication:

agent.run(
    "Summarise sales data",
    runtime_config={
        "mcp_configs": {
            mcp_id: {
                "authentication": {
                    "type": "api-key",
                    "key": "X-API-Key",
                    "value": "temporary-override"
                }
            }
        }
    }
)

Override allowed tools:

# Agent normally has access to ['get_weather', 'get_forecast']
# Restrict to only get_weather for this run
agent.run(
    "What's the current weather?",
    runtime_config={
        "mcp_configs": {
            mcp_id: {
                "allowed_tools": ["get_weather"]  # temporary restriction
            }
        }
    }
)

Configuration layers (resolution order):

1. Runtime config (highest priority) — per-execution overrides

2. Agent config — stored in agent mcp_configs

3. MCP config (lowest priority) — base MCP settings

Runtime overrides are processed in-memory for the run and do not modify stored MCP or agent 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.