Skip to content

agent-matrix/matrixlink

BranchesTags

Repository files navigation

⚡️ MatrixLink Suite

Production toolkit for MatrixHub — discover, select, and run MCP servers (orchestrators) and A2A agents across any cloud.

PyPI Version Python Versions GitHub Docs (MkDocs) License: Apache-2.0 Powered by matrix-hub

Requires Python 3.11+. Library published as matrixlink on PyPI. BFF/UI run on :8080.

MatrixLink Suite gives you a production-ready base to run MCP Gateway + Orchestrators (MCP Servers) + A2A Agents on any modern platform (IBM Code Engine, Google Cloud Run, AWS App Runner, Azure Container Apps, Knative/K8s, Local). It includes:

  • libs/matrixlink/ — PyPI-ready client for MCP discovery, A2A messaging, and Orchestrator invocation
  • apps/bff/ — Front Door (FastAPI) exposing a clean /api/* surface with admin & MCP proxy
  • ui/matrixhub-admin/ — Minimal React admin (read-only) for MCP servers & agents
  • infra/ce/ — IBM Code Engine scripts for apps + secrets
  • Makefile — Dev & ops targets (make help)

All services bind to port 8080. East–west calls use Bearer service tokens (optionally mTLS).

Default provider = local. No external services are required to run BFF + UI locally.

What are MatrixHub and MatrixLink?

MatrixHub is an internet-scale hub and search engine (think PyPI for AI agents & MCP servers). You use it to discover high-quality agents/orchestrators by capability (skills, flows), trust (publisher, SBOM/attestation), and fitness (success rate, latency, region). Import chosen entries into your org’s private catalog with the right visibility and policy.

MatrixLink is the runtime connector: a tiny client library plus an optional BFF that makes discovery and invocation portable across clouds. It lets your code:

  • Discover agents by skill via your MCP Gateway
  • Call agents with a simple A2A contract (/message/send, optional SSE)
  • Invoke orchestrators (/invoke/<flow>) with tenancy headers & bearer auth
  • Auto-resolve service endpoints via environment variables (no code edits per provider)

Together: discover globally, run locally. You pick building blocks from MatrixHub; MatrixLink wires them into your environment safely and repeatably.

Architecture

flowchart TD
  subgraph EXT["External"]
    UI["Clients / Apps / Chat UI"]
  end

  subgraph EDGE["API Gateway / Front Door (public)"]
    APIGW["https://your-host/api/*"]
  end

  subgraph CTRL["Control Plane"]
    MCP["MCP Gateway (registry, discovery, health)"]
  end

  subgraph RUNTIME["Serverless / Containers (:8080)"]
    BFF["BFF (Front Door + MCP proxy)"]
    ORCH["Orchestrator(s) (MCP Servers)"]
    A1["A2A Agents (skills)"]
    A2["A2A Agents (skills)"]
    AX["… more Agents"]
  end

  UI --> APIGW
  APIGW -- "/api/health|/api/ready|/api/mcp/*|/api/admin/*" --> BFF
  APIGW -- "/api/chat or /api/flows/<flow>" --> ORCH

  BFF --> MCP
  ORCH -.->|discover by skill| MCP
  ORCH --> A1
  ORCH --> A2
  ORCH --> AX
Loading

Public API (edge):

Path Target Notes
GET /api/health BFF liveness
GET /api/ready BFF readiness (+ MCP health)
POST /api/chat / /api/flows/* Orchestrator main chat/flow entrypoint
/api/mcp/* BFF → MCP proxied, secured
/api/admin/* BFF agents CRUD/run, secured

Repository layout

matrixlink-suite/
├─ libs/
│  └─ matrixlink/               # PyPI client
│     ├─ pyproject.toml
│     └─ src/matrixlink/
│        ├─ __init__.py
│        ├─ config.py
│        ├─ providers.py
│        ├─ discovery.py
│        ├─ a2a.py
│        ├─ orchestrator.py
│        ├─ sse.py
│        └─ errors.py
├─ apps/
│  └─ bff/
│     ├─ Dockerfile
│     ├─ requirements.txt
│     └─ app/
│        ├─ main.py
│        ├─ auth.py
│        ├─ db.py
│        ├─ models.py
│        ├─ observability.py
│        └─ clients/
│           ├─ mcp.py
│           └─ agents.py
├─ ui/
│  └─ matrixhub-admin/
│     ├─ Dockerfile
│     ├─ package.json
│     └─ src/...
├─ infra/
│  ├─ ce/                       # IBM Code Engine scripts
│  └─ secrets/
├─ docs/                        # MkDocs site (see below)
├─ mkdocs.yml                   # MkDocs config
├─ .env.example
├─ Makefile
├─ LICENSE
└─ README.md

Requirements

  • Python 3.10+
  • Node 18+ (UI)
  • Docker (for container builds)
  • Optional: IBM Cloud CLI for Code Engine deploys

Quickstart (local)

1) Run the BFF (Front Door)

make install
# optional: point BFF to a local MCP Gateway (if you run one)
export MCP_BASE_URL="http://localhost:4444"
make run-bff
# → http://localhost:8080/api/health

2) Run the Admin UI

make dev-ui
# → http://localhost:3000

For local testing, set export ADMIN_BEARER=changeme-admin-bearer-token and use the same in the UI Settings.

When do I need an MCP Gateway?

MatrixLink’s BFF and UI run fine without MCP for basic health/admin. You’ll want an MCP Gateway when you need:

  • Runtime discovery of agents/orchestrators by skill/tags
  • Central registry + RBAC and visibility per team/tenant
  • Health & fitness signals (route only to healthy entries)
  • Controlled rollouts (blue/green, canary via tags)

Local dev: you can run a lightweight MCP Gateway on http://localhost:4444. In cloud, point MCP_BASE_URL to your managed MCP instance (or resolve via DOMAIN_SUFFIX+MCP_SERVICE_NAME).

Environment variables

BFF

  • ADMIN_BEARER — token to guard /api/admin/* and /api/mcp/*
  • MCP_BASE_URL — MCP Gateway URL (defaults to http://localhost:4444 for CLOUD_PROVIDER=local)
  • MCP_BEARER_TOKEN — service token to call MCP Gateway
  • AGENTS_BASE_URL — optional static base for agents (fan-in host)
  • AGENTS_API_TOKEN — east–west bearer for agent invocations

MatrixLink lib

  • CLOUD_PROVIDER — local (default), ce, gcrun, apprunner, aca, knative
  • DOMAIN_SUFFIX — e.g. proj.region.codeengine.appdomain.cloud
  • MCP_SERVICE_NAME — default mcp-gateway
  • ORCH_SERVICE_NAME — default orchestrator
  • AGENTS_DOMAIN_PREFIX — default agents
  • MCP_BASE_URL, ORCH_BASE_URL, AGENTS_BASE_URL — explicit overrides
  • MCP_BEARER_TOKEN, A2A_SERVICE_TOKEN, TENANT_HEADER, REQUEST_TIMEOUT

Using MatrixLink (Python)

Install locally from repo:

cd libs/matrixlink
pip install -e .

Or from PyPI (after you publish):

pip install matrixlink

Discover an agent by skill (via MCP Gateway)

from matrixlink import MCPClient

mcp = MCPClient()  # reads MCP_BASE_URL or DOMAIN_SUFFIX + service name
agents = mcp.discover_agents(skill="report.generate")
print(agents[0]["endpoint"])  # https://agents.../agent-synth

Send data to an A2A agent

from matrixlink import A2AClient

a2a = A2AClient()  # uses A2A_SERVICE_TOKEN if set
endpoint = "https://agents.example.com/agent-synth"  # or from discovery
resp = a2a.send_message(endpoint, {"title": "Weekly Status", "bullets": ["A", "B", "C"]})
print(resp)

Invoke an orchestrator (MCP Server) flow

from matrixlink import OrchestratorClient

orch = OrchestratorClient("https://orchestrator.example.com")
result = orch.invoke("hr.orchestrate", {"candidates":[{"id":"c1","skills":["py","sql"]}]})
print(result)

Admin API (BFF)

Method Path Secured? Purpose
GET /api/health ❌ Liveness
GET /api/ready ❌ Readiness (+ MCP health)
GET /api/mcp/servers ✅ MCP servers list (proxy)
GET /api/mcp/tools ✅ MCP tools list (proxy)
POST /api/mcp/servers ✅ Create MCP server (proxy)
GET /api/admin/agents ✅ List agents
POST /api/admin/agents ✅ Create agent
POST /api/admin/agents/{id}/bind ✅ Bind agent → catalog URL
POST /api/admin/agents/{id}/run ✅ Invoke an agent by name

Secure = requires Authorization: Bearer ${ADMIN_BEARER}.

Docker

BFF

docker build -f apps/bff/Dockerfile -t local/bff:dev .
docker run --rm -p 8080:8080 \
  -e CLOUD_PROVIDER=local \
  -e ADMIN_BEARER=changeme-admin-bearer-token \
  -e MCP_BASE_URL=http://host.docker.internal:4444 \
  local/bff:dev

Admin UI

docker build -f ui/matrixhub-admin/Dockerfile -t local/matrixhub-admin:dev ui/matrixhub-admin
docker run --rm -p 8081:8080 local/matrixhub-admin:dev
# open http://localhost:8081

Deploy on IBM Code Engine (example)

  1. Create secrets (fill tokens first): ./infra/secrets/create-secrets.sh
  2. Build & push images: make docker-build-bff docker-build-ui make docker-push-bff docker-push-ui
  3. Create apps: make ce-create-bff make ce-create-ui
  4. API Gateway routes:
    • /api/health|/api/ready|/api/admin/*|/api/mcp/* -> BFF
    • /api/chat (or /api/flows/<flow>) -> Orchestrator (separate repo/app)

Other providers (env presets)

Google Cloud Run (custom domains recommended)

CLOUD_PROVIDER=gcrun
MCP_BASE_URL=https://mcp-gateway.example.com
ORCH_BASE_URL=https://orchestrator.example.com
AGENTS_BASE_URL=https://orchestrator.example.com
MCP_BEARER_TOKEN=...
A2A_SERVICE_TOKEN=...

AWS App Runner

CLOUD_PROVIDER=apprunner
MCP_BASE_URL=https://<apprunner-mcp-host>
ORCH_BASE_URL=https://<apprunner-orch-host>
AGENTS_BASE_URL=https://<apprunner-agents-host>

Azure Container Apps

CLOUD_PROVIDER=aca
DOMAIN_SUFFIX=myenv.azurecontainerapps.io
MCP_SERVICE_NAME=mcp-gateway
ORCH_SERVICE_NAME=orchestrator
AGENTS_DOMAIN_PREFIX=agents

Knative / K8s

CLOUD_PROVIDER=knative
DOMAIN_SUFFIX=apps.example.internal
MCP_SERVICE_NAME=mcp-gateway
ORCH_SERVICE_NAME=orchestrator
AGENTS_DOMAIN_PREFIX=agents

Local / Docker Compose + Traefik

CLOUD_PROVIDER=local
MCP_BASE_URL=http://localhost:4444

Security & Ops

  • Secrets: store tokens in provider secret stores; never in images
  • Auth: OIDC/JWT at edge for /api/chat; ADMIN_BEARER for admin proxy; service Bearer for east–west
  • Observability: structured logs with X-Request-ID / X-Tenant-Id; add OTEL exporters if desired
  • SSE: ensure the API Gateway does not buffer /stream responses
  • Scaling: BFF & MCP Gateway minScale=1; Orchestrators/Agents can scale to 0
  • DB: BFF uses SQLite for dev; switch to a managed DB in prod via DATABASE_URL

Make targets

make help              # list targets
make install           # venv + deps + install local matrixlink into BFF venv
make run-bff           # run BFF at :8080 (local)
make dev-ui            # run Admin UI at :3000 (Vite dev)
make build-ui          # build Admin UI static
make build-lib         # build matrixlink (wheel/sdist)
make docker-build-bff  # build BFF container
make docker-build-ui   # build UI container
make docker-push-bff   # push BFF image
make docker-push-ui    # push UI image
make ce-create-secrets # create CE secrets
make ce-create-bff     # create BFF app on CE
make ce-create-ui      # create UI app on CE

Troubleshooting

  • ModuleNotFoundError: matrixlink when running BFF locally → run make install.
  • MCP base URL not set → set MCP_BASE_URL or use CLOUD_PROVIDER + DOMAIN_SUFFIX + MCP_SERVICE_NAME.
  • CORS → set CORS_ALLOW_ORIGINS in BFF (e.g., http://localhost:3000).
  • 401 on admin routes → set ADMIN_BEARER and pass Authorization: Bearer <token> from the UI.

License

Apache 2.0 — see LICENSE.

About

MatrixLink Suite gives you a production-ready base to run MCP Gateway + Orchestrators (MCP Servers) + A2A Agents on any modern platform (IBM Code Engine, Google Cloud Run, AWS App Runner, Azure Container Apps, Knative/K8s, Local).

Resources

Readme

License

View license

Security policy

Security policy
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.1.0 Latest
Sep 20, 2025

Packages

 
 
 

Contributors

Languages