APIs are becoming AI tools. Who governs the calls?
AI agents are starting to call internal systems: billing, CRM, identity, logistics, support, legacy SOAP services, and private REST APIs.
The hard part is not only making an API callable by an agent. The hard part is answering:
Which agent called which API, under which identity, through which policy, with which quota, and with what audit trail?
STOA is an open-source Agent Gateway that sits next to your existing API gateway and exposes enterprise APIs as governed Model Context Protocol (MCP) tools.
No gateway replacement. No duplicated API catalog. No untracked agent traffic.
What you can do with STOA
| In your platform today | With STOA |
|---|
| APIs live behind Kong, Gravitee, Apigee, Azure APIM, AWS API Gateway, or webMethods | Keep them where they are and add an MCP layer for agents |
| Developers wait for access, credentials, and onboarding | Use a self-service portal for discovery, subscription, and testing |
| API catalogs drift between specs, spreadsheets, and gateways | Define APIs once and expose them as REST endpoints and MCP tools |
| AI agents call tools without enterprise-grade controls | Apply OAuth, mTLS, rate limits, RBAC, quotas, and audit trails |
| Teams lack visibility into AI-to-API traffic | Observe calls with Prometheus, Grafana, Loki, and OpenSearch |
Quick start
Run the full local stack with Docker Compose.
# Clone
git clone https://github.com/stoa-platform/stoa.git
cd stoa/deploy/docker-compose
# Start the demo stack
cp .env.example .env
docker compose up -d
# Wait for services to become healthy
../../scripts/demo/check-health.sh --wait
# Seed demo data
../../scripts/demo/seed-all.sh --skip-traffic
Open http://localhost and log in with:
username: halliday
password: readyplayerone
| Service | URL |
|---|
| Console | http://localhost |
| Developer Portal | http://localhost/portal |
| API Docs | http://localhost/api/docs |
| Grafana | http://localhost/grafana |
| Keycloak | http://localhost/auth |
| Gateway health | http://localhost/gateway/health |
For local component-by-component development, see DEVELOPMENT.md.
Access-control quickstart
quickstart/ starts the control plane, PostgreSQL, Keycloak, STOA Gateway, and a fake backend. You need Bash, curl, openssl, Docker Engine, and Docker Compose 2.1.1 or newer (docker compose up --wait). GNU timeout bounds the startup; it is absent on macOS — use gtimeout from coreutils, or perl -e 'alarm shift; exec @ARGV' 300 docker compose up --wait. The full prerequisite table is in the quickstart README.
The API is declared with POST /admin/contracts and inboundAuth on the gateway. POST /v1/tenants/{id}/apis on the control plane publishes the route without a valid JWT policy, so the control plane does not protect that route. A later version will declare the API through the control plane.
cd quickstart
timeout 300 docker compose up --wait
./verify.sh
verify.sh declares the API, expects 401 without a token, 401 with an invalid token, then 200 with a Keycloak token. Host ports are bound to 127.0.0.1. The gateway image built here is stoa-quickstart-gateway:0.9.25.
From API to agent tool in 3 steps
graph LR
A[Import or define an API] --> B[Attach auth, quotas, policies]
B --> C[Publish REST + MCP]
C --> D[Agents discover tools]
C --> E[Humans keep using REST]
D --> F[Audit, metrics, traces]
E --> F
- Define once — import OpenAPI or describe the API through STOA's Universal API Contract.
- Govern once — attach identity, plans, rate limits, scopes, and tenant policies.
- Expose everywhere — publish for human developers through REST and for AI agents through MCP.
Why teams choose STOA
MCP-native, not MCP as an afterthought
STOA is built for AI agents that need to discover and call enterprise APIs safely. Agents connect through MCP; platform teams keep control over identity, authorization, rate limiting, and audit.
Sidecar by design
STOA does not force a big-bang gateway migration. Existing REST traffic continues through your current gateway while STOA adds a governed MCP path for agents.
Open source and self-hostable
The core platform is Apache 2.0. Run it locally, in Kubernetes, on-premise, or in a hybrid setup. Fork it, inspect it, extend it, or contribute back.
Built for European and regulated environments
STOA is designed for teams that care about sovereignty, auditability, data residency, and operational control. It supports self-hosted deployments and keeps governance close to your infrastructure.
Architecture
STOA Control Plane
┌──────────────────────────────────────────────────┐
│ Console · Portal · Control Plane API · Keycloak │
│ Observability · Tenants · Subscriptions · Audit │
└───────────────────────┬──────────────────────────┘
│ sync
┌──────────────────┴──────────────────┐
│ │
▼ ▼
┌──────────────────────────┐ ┌─────────────────────────────┐
│ STOA Agent Gateway │ │ Existing API Gateway │
│ Rust · MCP · REST bridge │ │ Kong · Gravitee · Apigee │
│ OAuth · mTLS · quotas │ │ Azure APIM · AWS · webMethods│
│ Tool discovery · audit │ │ Existing REST clients stay │
└─────────────┬────────────┘ └──────────────┬──────────────┘
│ │
▼ ▼
AI agents via MCP Existing backends
Core idea: STOA adds a governed agent layer without taking ownership of your whole API estate.
Platform capabilities
| Capability | What it gives you |
|---|
| MCP Gateway | Governed tool discovery and execution for AI agents |
| Universal API Contract | One definition for REST and MCP exposure |
| Self-Service Portal | API discovery, subscriptions, credentials, and testing |
| Admin Console | Tenants, consumers, APIs, plans, subscriptions, and policies |
| Multi-Gateway Adapters | Sync with Kong, Gravitee, Apigee, Azure APIM, AWS API Gateway, webMethods, and STOA native |
| Identity Federation | Keycloak-based OIDC, SAML, LDAP, Active Directory, and cross-realm isolation |
| Security Controls | OAuth 2.1, PKCE, mTLS, JWT validation, RBAC, quotas, and per-consumer rate limiting |
| Observability | Prometheus metrics, Grafana dashboards, Loki logs, OpenSearch error snapshots, traces, and audit history |
| Kubernetes Native | Helm deployment, operator support, and CRDs for tools, toolsets, skills, gateways, and bindings |
Demo scenarios
After seeding the demo stack, try these flows:
| Scenario | What to look for |
|---|
| Developer discovers an API | Open the Portal, browse the API catalog, inspect specs, and request access |
| Admin approves and governs access | Use the Console to manage consumers, plans, subscriptions, tenants, and quotas |
| Agent calls an API as a tool | Observe how MCP traffic is authenticated, rate-limited, traced, and audited |
| Platform team monitors usage | Open Grafana and inspect latency, request rate, errors, quotas, and gateway health |
Who is STOA for?
Platform teams who already run API gateways and want an AI agent layer without replacing their infrastructure.
Integration teams modernizing legacy REST, SOAP, and webMethods APIs for agentic workflows.
AI teams that need real enterprise tools, not toy demos, with authentication, quotas, and audit from day one.
Open-source builders who believe the agentic web needs inspectable, self-hostable, standards-based infrastructure.
Under the hood
| Component | Stack | Purpose |
|---|
| Control Plane API | Python, FastAPI, SQLAlchemy | Backend API, RBAC, adapters, tenants, subscriptions |
| Console UI | React, TypeScript, Vite | Admin experience for platform teams |
| Developer Portal | React, TypeScript, Vite | Self-service API discovery and onboarding |
| STOA Gateway | Rust, Tokio, axum | API proxy, MCP bridge, auth, quotas, audit |
stoactl | Go, Cobra | CLI and GitOps-style operations |
| Keycloak | OIDC, SAML, LDAP | Identity, federation, realms, authentication |
| Kubernetes Operator | Python, Kopf | CRD controller for MCP resources |
| Helm Chart | Helm 3 | Kubernetes installation and production deployment |
Quality and security
STOA is built as infrastructure, not a demo script.
| Area | Practice |
|---|
| Gateway tests | Unit, contract, integration, and security tests |
| Control plane tests | Async API tests with coverage threshold |
| E2E tests | Playwright + BDD feature files for smoke, critical, portal, console, and gateway flows |
| Supply chain | SAST, dependency scanning, container scanning, SBOM generation, signed commits, and regression guards |
See SECURITY.md, CONTRIBUTING.md, and docs/ for details.
Deploying STOA
Docker Compose
Use Docker Compose for local demos, development, and evaluation.
cd deploy/docker-compose
cp .env.example .env
docker compose up -d
See deploy/docker-compose/README.md.
Kubernetes
Use Helm for Kubernetes deployments.
helm install stoa-platform ./charts/stoa-platform \
-n stoa-system --create-namespace \
-f charts/stoa-platform/values.yaml
See the deployment documentation for production and hybrid environments.
Repository map
stoa/
├── control-plane-api/ # FastAPI backend
├── control-plane-ui/ # React admin console
├── portal/ # React developer portal
├── stoa-gateway/ # Rust gateway + MCP bridge
├── stoa-go/ # Go CLI and connect agent
├── stoa-operator/ # Kubernetes operator
├── charts/ # Helm chart and CRDs
├── deploy/docker-compose/ # Local quick start
├── e2e/ # Playwright BDD tests
├── scripts/ # Demo, seed, benchmarks
└── docs/ # Runbooks, ADRs, methodology
Contributing
STOA is early, open, and looking for builders who care about making AI-to-API traffic safe, observable, and self-hostable.
Great places to contribute:
- Gateway adapters — Kong, Gravitee, Apigee, Azure APIM, AWS API Gateway, webMethods, and more.
- MCP examples — agent clients, tool definitions, demo workflows, Claude/Cursor integrations.
- Security hardening — OAuth, mTLS, RBAC, policy evaluation, audit, threat modeling.
- Observability — dashboards, traces, error snapshots, benchmark scenarios.
- Docs and tutorials — quick starts, migration guides, architecture notes, real-world examples.
- Developer experience —
stoactl, local setup, test ergonomics, CI, Helm values.
Start with CONTRIBUTING.md, open an issue, or join the community on Discord.
Documentation and community
Related repositories
License
STOA is released under the Apache License 2.0.
