Skip to main content

Keyban-infra MCP Server - Quick Start

Connect your AI assistant to Keyban infrastructure in 2 minutes.

Step 1: Choose Your Environment​

  • Production: https://api.prod.keyban.io/mcp

Step 2: Get an API Key (authentication)​

Administrators can create and manage keys from the Keyban Admin Dashboard.

Step 3: Configure Your Client​

🧰 Codex CLI​

  1. Open (or create) the Codex config file:

    • macOS/Linux: ~/.codex/config.toml
    • Windows: %USERPROFILE%\.codex\config.toml

  2. Add this configuration (Local example):

[mcp_servers.keyban-infra]
url = "https://api.keyban.localtest.me/mcp"
http_headers = { "X-API-KEY" = "YOUR_API_KEY_HERE" }

  1. Switch to another environment by replacing the URL:

    • Testing: https://api.testing.keyban.io/mcp
    • Production: https://api.prod.keyban.io/mcp

  2. Restart your Codex session or run codex reload to apply the changes.

🔍 Test with MCP Inspector​

Spin up the Inspector to validate that your server, transport, and credentials work before plugging an assistant in.

Web UI (no install)

npx -y @modelcontextprotocol/inspector \
  --transport http \
  --server-url https://api.prod.keyban.io/mcp \
  --header "X-Api-Key: YOUR_API_KEY_HERE"

The command opens the Inspector in your default browser with the connection details pre-filled over HTTP/SSE. Choose your environment by swapping the URL above for https://api.testing.keyban.io/mcp or https://api.prod.keyban.io/mcp. Repeat --header to add extra headers if needed. A successful connection shows every tool, resource, and argument completion exactly as an assistant will see them.

What You Can Do​

Once connected, your AI assistant can automate day-to-day Keyban admin tasks:

🗂️ Manage applications without the dashboard​

"List every application in our org and show their IDs."

"Find the application named 'Loyalty Portal' and update its description to 'Pilots Spring 2025'."

Use list_applications, get_application, update_application, or even create_application to keep configs up to date in seconds.

🎯 Tune loyalty programs in real time​

"Fetch the loyalty settings for the 'Paris Flagship' application and set currencyToPointRatio to 3."

"Increase the welcome bonus for 'Paris Flagship' to 15 points."

The get_loyalty_settings resource and update_loyalty_settings tool let you adjust earning rules, redemption thresholds, or branding directly from your assistant—no back-office clicks required.

📦 Control digital product passport (DPP) access​

"Show me all claim permissions for the 'Heritage Collection'."

"Create a new claim permission granting alice@example.com access to DPP 'scarlet-scarf-001'."

Tools like list_claim_permissions, create_claim_permission, and delete_claim_permission help you keep DPP distribution under control.

🏪 Keep point-of-sale details current​

"List the points of sale and highlight which ones have missing geolocation."

"Update the phone number for the 'Lyon Part-Dieu' POS."

Combine list_points_of_sale, get_point_of_sale, and update_point_of_sale to maintain customer-facing data across locations.

Troubleshooting​

❌ Connection Failed​

  • ✅ Check server URL is correct
  • ✅ Verify you're using HTTPS (not HTTP)
  • ✅ Ensure server is running

🔒 401 Unauthorized​

  • ✅ Check your token/API key is correct
    • ✅ Verify the header name matches (X-Api-Key)
  • ✅ Ensure token hasn't expired

🤔 Server Not Appearing​

  • ✅ Restart your client application
  • ✅ Check config file syntax (valid JSON)
  • ✅ Look for error messages in client logs

Need Help?​

  1. Test first: Use MCP Inspector to verify server is working
  2. Check logs: Look at server logs for error messages
  3. Verify auth: Make sure your token/API key is active