Cortex Gateway is a federated MCP gateway that provides a single, OAuth-protected entry point to multiple internal backends and native MCP servers, enforcing zero-trust principles for AI agents.
Core capabilities:
whoami — Returns your full OAuth identity (email, sub, scopes, client, jti) and aggregated role/identity information from all federated backends, helping you understand who you are and what you're permitted to do.
list_cortex_resources — Discovers all MCP resources exposed by the gateway (e.g., architecture docs, dynamic backend resources via URI templates). Useful for clients that don't natively surface the MCP resources primitive.
read_cortex_resource — Reads a specific resource by URI (e.g., cortex://architecture), returning Markdown or JSON content.
report_missing_capability — Files a signal ticket when no available tool fulfills a request, or an existing tool is insufficient. Supports severity levels (blocking, inconvenient, nice_to_have), auto-deduplicates within 24 hours, and returns a ticket ID.
list_cortex_tickets — Views your previously filed capability tickets, filterable by status, severity, and backend, so you can track progress and avoid duplicate filings.
Under the hood, the gateway aggregates tools from multiple backends into a unified catalog, dynamically discovers new tools every 60 seconds, enforces per-user OAuth 2.1 scope-based permissions, and maintains a pseudonymized audit trail of all tool calls.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cortex Gateway show me the tools I have access to"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A federated MCP gateway: one spec-compliant, OAuth-protected MCP server in front of N plain-HTTP backends.
Your business apps stay ordinary web services. Each one exposes a single
POST /api/cortex/backend endpoint (a ~120-line contract, no MCP library, no
stdio). The gateway discovers their tools, merges them into one MCP catalog,
enforces OAuth 2.1 + scopes, routes tools/call to the owning backend, and
keeps a pseudonymized audit trail.
Built for one requirement: everyone in a company should be able to hand their own agent the keys — with exactly that person's rights, nothing more, nothing less. And when agents become autonomous assistants, the answer stays the same: the agent borrows the person's identity, the apps keep enforcing that person's rights. The gateway decides nothing, so there is nothing new to trust.
Put another way: zero-trust principles for AI agents — the missing link between your IAM (who your users are, what they may do) and the MCP ecosystem (how agents call tools). Not a full ZTNA product; the identity-and-access layer for agents.
A backend is a dedicated MCP reduced to its essence: a tool catalog plus tool invocation (and optional prompts/resources) over bare HTTP JSON-RPC — the transport and lifecycle machinery (initialize, sessions, SSE, version negotiation) lives once, in the gateway. Because the contract is a semantic subset of MCP, a native MCP server can also be federated through the built-in MCP→backend proxy adapter (docs/mcp-adapter.md).
[MCP agent: Claude Desktop / claude.ai Custom Connector / any MCP client]
│ HTTPS + OAuth 2.1 JWT (Bearer)
▼
[cortex-gateway] ←— thin gateway, no business logic
│ HTTPS + the same JWT propagated (RFC 8707)
▼
[your backends] ←— domain owners, plain HTTP, own their ACLsPermissions match the underlying app, automatically, at the user level. The gateway never copies or mirrors permissions — it propagates the real user identity (your JWT to first-party backends, the user's own linked token to proxied third-party MCP servers), so each app's native permission model applies per user, with nothing to sync and no service-account flattening. Unlike hosted tool aggregators, the token vault and the audit trail stay on your infrastructure.
One perimeter, not N connectors. Wiring each app as its own MCP connector also keeps native permissions — and leaves you with N consents, N token stores, no shared audit, no cross-app entitlements, and a flooded tool list. The gateway collapses that to one OAuth surface without giving up the per-user model: aggregation without permission loss.
Zero MCP lock-in in your apps. Backends speak a minimal JSON-RPC contract over plain HTTP. Remove the gateway and you can still call them directly (tests, batch jobs, other integrations).
One JWT, N backends. The agent authenticates once; the gateway propagates the token; every backend re-validates it and applies its own permissions. Revocation at the authorization server cuts everything.
Failure isolation. An unreachable backend just disappears from
tools/list; the rest keeps working.
Context-aware federation. Backend filtering and a compact "search" mode keep the tool catalog from flooding the agent's context (docs/tool-search-mode.md).
Agent feedback loop. Agents can file report_missing_capability
tickets when a tool is missing or insufficient — deduplicated, triaged,
optionally pushed to a webhook when blocking.
Related MCP server: Multi-MCP Hub
Company-wide agent surface. An organization runs N internal apps (CRM, quality docs, billing, analytics...). Each app adds the ~120-line backend endpoint; the gateway exposes them as ONE MCP connector protected by the company's SSO. Employees plug a single URL into Claude Desktop / claude.ai and get exactly the tools their token scopes allow, with a central audit trail. This is the setup the gateway was born in.
Product builder. You ship several products and want agents (yours or your customers') to operate them. Instead of maintaining one MCP server per product, every product implements the backend contract and the gateway is your single, versioned, OAuth-protected agent API. Adding a product to the agent surface is one env var.
Thematic hub / curated registry. Run a gateway as a topic endpoint —
e.g. "all open-data tools for domain X" — that federates several providers
behind one URL with one token. The scope model gives you per-provider
opt-in, get_help/get_snapshot give agents self-describing discovery, and
the audit trail tells you what is actually used. Providers either speak the
(deliberately tiny) backend contract natively, or — for off-the-shelf MCP
servers — get fronted by the built-in MCP→backend proxy adapter
(docs/mcp-adapter.md).
Free / paid tool tiers. Scopes are entitlements. Let your authorization
server grant mcp:yourapp:basic to free users and mcp:yourapp:pro to
paying ones (your billing webhook updates the grant): the gateway then shows
and allows each caller exactly the tools of their plan — no paywall logic in
the gateway or the backends, tools just declare their scope. Revocation and
downgrades propagate through the normal OAuth chain.
The built-in MCP→backend proxy adapter lets a bundle mix contract backends and off-the-shelf native MCP servers (Canva, Figma, ...): the adapter is an MCP client downstream (initialize, sessions, SSE framing) and a plain backend upstream, so the gateway core does not change. Per-user downstream OAuth is handled by a token vault (AES-256-GCM at rest) and a linking flow (RFC 9728 discovery, Dynamic Client Registration, PKCE): each user consents once per provider, then agents are identified on the whole bundle with a single Cortex token. See docs/mcp-adapter.md for a worked "design bundle" example (Canva + Figma + your own backend).
Machine identity for discovery — replace the static technical token
with a client_credentials flow once your AS supports it.
Shared event bus / rate-limit store — for multi-instance deployments.
MCP spec 2025-06-18 (Streamable HTTP transport: POST JSON-RPC, GET SSE
for listChanged notifications, DELETE session termination)
Primitives: tools, resources (incl. URI templates), prompts
OAuth 2.1 resource server: JWKS verification, audience per resource (RFC 8707), protected-resource metadata (RFC 9728), optional RFC 7662 introspection for revocation
Scope-based visibility: agents only see (and can call) the tools their
token scopes allow; scopes_supported in discovery is derived live from
the federated catalog
Dynamic discovery: backends are polled every 60s; new tools appear
without redeploying the gateway, with SSE tools/list_changed push
Builtins: whoami (aggregated identity across backends),
find_tools, report_missing_capability, list_cortex_tickets,
list_cortex_resources, read_cortex_resource, plus a self-describing
cortex://architecture resource generated live
Audit trail: one JSON line per call on stdout (hashed email, hashed params) + optional PostgreSQL persistence with retention cron
Origin allow-list (anti DNS-rebinding), per-token rate limiting, optional pool sandbox
git clone https://github.com/wellknownmcp/cortex-gateway
cd cortex-gateway
npm install
# 1. Start the demo backend (dependency-free)
node examples/demo-backend/server.mjs &
# 2. Configure the gateway
cat > .env.local <<'EOF'
OAUTH_ISSUER=https://auth.example.com
CORTEX_BACKENDS=demo
CORTEX_BACKEND_DEMO_URL=http://127.0.0.1:4820
CORTEX_TECHNICAL_TOKEN=demo-technical-token
CORTEX_DEV_BYPASS_TOKEN=dev-secret
CORTEX_DEV_BYPASS_SCOPES=mcp:demo:read
EOF
# 3. Run it
npm run dev
# 4. Talk MCP (dev bypass replaces the Bearer JWT locally)
curl -s http://localhost:3213/mcp \
-H 'Content-Type: application/json' \
-H 'X-Dev-Mode: dev-secret' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'
# → whoami, ..., demo_get_help, demo_echo, demo_get_time
curl -s http://localhost:3213/mcp \
-H 'Content-Type: application/json' \
-H 'X-Dev-Mode: dev-secret' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"demo_echo","arguments":{"message":"hello"}}}' | jqIn production you point OAUTH_ISSUER at your OAuth 2.1 authorization
server (any server that issues RS256 JWTs with a JWKS endpoint and supports
the scope claim), and MCP clients connect to https://your-host/mcp with
a Bearer token whose aud is the gateway's canonical URI.
The gateway is a remote Streamable HTTP server, but some MCP clients — and
the Docker inspection harnesses of directories like Glama — only speak the
stdio transport. scripts/stdio-bridge.mjs bridges the two: it boots the
production build against an ephemeral local OAuth issuer (the real JWT
verification path, no bypass), mints itself a short-lived token, and relays
newline-delimited JSON-RPC between stdin/stdout and POST /mcp.
npm run build
npm run start:stdio # stdio MCP server on stdin/stdoutSelf-granted scopes come from BRIDGE_SCOPES (gateway builtins need none);
the gateway port from BRIDGE_GATEWAY_PORT (default 3213). Design notes and
the gotchas (stdout purity, protocol-version negotiation, session echo):
https://cortex-gateway.dev/guides/expose-http-mcp-server-over-stdio/.
Implement the contract in your app — one POST endpoint, list_tools +
your tools (docs/backend-contract.md, reference
implementation in examples/demo-backend/).
Declare it:
CORTEX_BACKENDS=demo,docs
CORTEX_BACKEND_DOCS_URL=http://127.0.0.1:4001Done. The gateway discovers docs_* tools within 60s and pushes
tools/list_changed to connected clients.
Everything is env-driven — see .env.example for the full annotated list. The essentials:
Variable | Required | Purpose |
| prod | Canonical MCP resource URI (RFC 9728), default JWT audience |
| yes | Your OAuth 2.1 authorization server |
| yes | Federated backends |
| yes | Static token for catalog discovery (catalog methods only) |
| prod | Web origins allowed (exact or |
| no |
|
| with | Secret for |
| with | Where approved tool definitions persist; without it a restart re-approves the current state |
| no | Ed25519 signing of that store. Public key alone = the gateway verifies approvals but cannot mint them |
| no | Baseline scope demanded before any dispatch |
| no | PostgreSQL for audit persistence + gateway tickets |
| no | Webhook for blocking missing-capability tickets |
| no |
|
Two paths, and the difference between them is the whole design: the catalog is discovered in the background with a technical token that can only list, and a call carries the user's own token all the way to the backend.
sequenceDiagram
autonumber
participant Agent as AI agent
participant GW as Cortex Gateway
participant AS as Authorization server
participant App as Backend app
rect rgba(128,128,128,0.10)
note over GW,App: Catalog refresh — every 60s, no user involved
GW->>App: tools/list (CORTEX_TECHNICAL_TOKEN)
App-->>GW: full tool catalog
note over GW: Fingerprint each definition<br/>(rug-pull detection)
end
note over GW,AS: JWKS fetched once and cached —<br/>tokens are verified locally, not per call
Agent->>GW: tools/list (user JWT)
note over GW: Verify signature, issuer, audience<br/>Filter the cached catalog by the token's scopes
GW-->>Agent: only the tools this user may call
Agent->>GW: tools/call demo_echo (user JWT)
note over GW: Check the scope declared by that tool
GW->>App: tools/call — the user's JWT, forwarded
note over App: Applies its own roles and ACLs<br/>to that user
App-->>GW: result, under the user's own rights
GW-->>Agent: result
note over GW: One audit line: who, which tool,<br/>which backend, which scopeThe agent never holds a credential the user does not have, and no over-privileged service account exists anywhere on the path.
Agent access is secured by construction, not by gateway policy. The properties below are what to demand from any MCP tooling you wire into an AI app:
OAuth 2.1, not shared API keys — every caller authenticates as themselves; tokens are per-user, scoped and revocable.
No permission flattening — the real user's identity is propagated to each backend, so no over-privileged service account exists and the agent gets exactly the user's own rights.
Least privilege — the tool catalog is scope-filtered per caller; agents only see the tools their token allows.
Verifiable — the whole OAuth discovery chain is walkable without a token, so you (or a third-party scanner) can confirm the posture before connecting.
Under the hood:
The gateway decides nothing about business permissions. OAuth scope is the front door (checked twice: gateway + backend); application roles and ACLs live in each backend.
The static technical token can only reach catalog methods (src/contract/static-token.ts); every data method requires the end user's JWT.
Audit is pseudonymized by design (hashed email, hashed params). Pseudonymized is not anonymous: hashed identifiers remain personal data under GDPR Art. 4(5), so the audit trail stays in your record of processing and needs a retention period.
Sessions are bound to the token's sub; foreign session ids get 404.
Controls a federating gateway can enforce that a single server cannot. Because it sees every backend's tool definitions and every hop to them, the gateway is the place to catch what the ecosystem's incident reports keep finding — full details in docs/security.md:
Rug-pull detection. Tool definitions are fingerprinted (description,
inputSchema, scope, version) at first sight and re-checked at every
refresh. A backend that rewrites what a tool claims to do while keeping its
name is reported, and with CORTEX_TOOL_INTEGRITY_MODE=block the tool is
quarantined until an operator reviews it over /api/admin/tool-integrity —
an HTTP endpoint, not an MCP tool, so a model cannot clear a rug pull on its
own. Name-level change detection — what most implementations do — misses
exactly this attack.
No plaintext to remote hosts. Every federated call forwards the caller's
token, so an http:// backend URL pointing anywhere but loopback is refused
at load. Same validation on the OAuth endpoints the adapter discovers from
a third-party server's metadata, which is the class of bug behind
CVE-2025-6514.
Attributable audit. Each line records which backend served the call and under which scope — not just the tool name.
Honest scope: approvals persist across restarts (CORTEX_TOOL_BASELINE_FILE)
but the store is not signed, so this proves "this definition changed since you
approved it here", not "this is the definition the vendor published".
Operator-signed baselines are the next step, not a claim being made today.
Compliance. These are the controls audits test for on automated access: least-privilege scopes, per-user identity (no over-privileged service account), a per-call attributable audit trail, and central revocation. They map to ISO 27001:2022 Annex A access-control and logging controls (A.5.15, A.5.16, A.5.17, A.5.18, A.8.2, A.8.15, A.8.16) and to SOC 2 CC6/CC7 — both of which apply today. The EU AI Act articles usually cited (Art. 12 record-keeping, Art. 14 human oversight) govern high-risk AI systems only, and after the 2026 Digital Omnibus those obligations were deferred to 2 Dec 2027 (stand-alone Annex III) and 2 Aug 2028 (Annex I embedded); most internal agent deployments are not high-risk, and a gateway is access infrastructure rather than an AI system. Self-hosted means the audit trail and token vault stay in your perimeter — no extra sub-processor under GDPR Art. 28, none in your SOC 2 scope. Cortex supplies the controls, not a certification. Full mapping: https://cortex-gateway.dev/answers/ai-agent-compliance-controls/
npm run typecheck # tsc --noEmit
npm test # vitest
npm run build # prisma generate + next buildThe database is optional in every environment: without CORTEX_DATABASE_URL
the audit stays on stdout and gateway-local tickets are disabled.
Lists the MCP resources exposed by the gateway (self-describing architecture document, dynamic backend resources through URI templates). Wrapper tool over the resources/list channel, needed because some MCP clients do not surface the resources primitive in their visible tool palette.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses it is a wrapper over resources/list channel and mentions the resource types. But it lacks detail on return format, pagination, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines purpose and scope, second explains rationale. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list tool with no output schema, the description provides adequate context about what is listed and why it exists. It could note if pagination or ordering applies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so baseline is 4. The description adds no parameter info but explains the output content, which is useful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists MCP resources from the gateway, including specific resource types like self-describing architecture document and dynamic backend resources. It distinguishes itself from sibling tools like list_cortex_tickets and read_cortex_resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains it is needed when MCP clients do not surface the resources primitive. However, it does not explicitly state when not to use it or compare to alternatives like read_cortex_resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists your own previously filed report_missing_capability tickets (auto-filtered by OAuth identity — you do not see other agents' tickets). Useful before re-filing a ticket, or to follow a ticket's status after triage by the platform team.
Possible statuses: open (just filed), triaged (the team looked at it), planned (work scheduled), resolved (capability shipped, resolvedPrUrl points at the PR), wont_fix (deliberately not implemented, triageNote explains why), duplicate (merged with another).
Returns: { tickets: [{ id, status, severity, contextTool, contextApp, whatIWanted, suggestedShape, triageNote, resolvedPrUrl, createdAt, updatedAt }] }, sorted by createdAt desc, max 100.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of tickets returned. Default 20, max 100. | |
| status | No | Filter by status. Optional. | |
| severity | No | Filter by severity as declared at filing time. Optional. | |
| contextApp | No | Filter by backend (a backend id, or 'cortex'). Optional. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses auto-filtering by OAuth identity, possible statuses with meanings, and return format. This is transparent and adds context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: first sentence for purpose, bullet for statuses, line for return format. No wasted words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description provides the full return shape with fields and sorting. It explains auto-filtering, statuses, and filter options, making the tool completely self-contained for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 4 parameters described). The description adds value by stating default limit (20), max limit (100), and listing status/enum values again, reinforcing the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists your own previously filed tickets, auto-filtered by OAuth identity. It distinguishes from sibling tools like report_missing_capability (filing) and list_cortex_resources/read_cortex_resource (different resources).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it's useful before re-filing a ticket or to follow status after triage, giving clear context. It could be more explicit about when not to use, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads an MCP resource by URI (e.g. cortex://architecture, docs://document/42). Wrapper tool over the resources/read channel. Returns Markdown or JSON depending on the resource. Use after list_cortex_resources to discover available URIs.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | Resource URI (e.g. 'cortex://architecture'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions it's a wrapper over resources/read and returns Markdown or JSON, but does not state it is read-only, safe, or describe error handling for invalid URIs. Adequate but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: action with examples, implementation detail, return format, and usage hint. No wasted words, front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter, the description covers what it does, how to use it, and return formats. Does not mention error scenarios or supported URI schemes beyond examples, but is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single 'uri' parameter already described in the schema. The description adds examples but no additional semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads an MCP resource by URI, provides examples (cortex://architecture, docs://document/42), and distinguishes from the sibling list_cortex_resources which lists URIs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Use after list_cortex_resources to discover available URIs', setting clear usage context. Does not explicitly mention when not to use or alternatives, but the sibling list is referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports a missing capability or an insufficient tool to the platform team. Use it when you cannot fulfil a user request because no MCP tool offers what is needed, OR when an existing tool limits you (incomplete return, missing parameter, unhelpful error, ...).
Typical example: the user asks for a link to a file; you search the returns of list_files / read_file, there is no webUrl field; you report the missing capability. The platform team prioritizes and ships the field in a next release.
Principle: your ticket is a SIGNAL, not an implementation order. Several converging tickets = a priority. Do not hesitate to report even when unsure — noise is filtered at triage. Do NOT report an obvious bug (the API returns 500) — let the error surface naturally instead.
Auto-dedup: an identical ticket (same description + same tool + same agent) within 24h just refreshes the timestamp instead of creating a duplicate.
Before reporting, consider calling list_cortex_tickets to check you have not already filed a similar ticket — avoids re-filing in a loop.
Returns: { ticketId, deduplicated, ackMessage }.
| Name | Required | Description | Default |
|---|---|---|---|
| severity | Yes | blocking = you cannot answer the user. inconvenient = workaround exists but with friction. nice_to_have = ergonomic improvement. | |
| contextApp | No | Backend concerned (a backend id, or 'cortex' for the gateway itself). Optional but very useful for triage. | |
| userIntent | Yes | Why the user needed this capability. Helps understand the business value. | |
| contextTool | No | Name of the MCP tool you tried / wanted to use (e.g. 'list_files'). Optional. | |
| whatIWanted | Yes | The missing capability, in natural language. E.g. 'Give the user a clickable link to a file'. | |
| suggestedShape | No | If you have an idea of the tool signature or returned field, suggest it. E.g. 'Add `webUrl: string` to the list_files return'. Optional. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: the tool is a signaling mechanism, not an implementation order; auto-dedup with 24h window; return fields. It clearly sets expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured with paragraphs and bullet points. It is front-loaded with purpose and each section adds value, though some redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a reporting tool: covers purpose, usage, dedup, return structure, and pre-reporting checks. No output schema exists, but the description explains returns in text, making it self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters clearly. The description adds no extra meaning beyond the schema, thus baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: reporting a missing capability or insufficient tool. It distinguishes itself from siblings by providing explicit use cases and examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives detailed guidance on when to use (unfulfillable requests, tool limitations) and when not to (obvious bugs). It suggests checking existing tickets and explains auto-dedup, providing comprehensive usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the caller's OAuth identity (email, sub, pool, scopes, client, audience, jti) and aggregates the whoami of every healthy federated backend (effective role in that backend, derived capabilities). Useful to know who you are and what you may do before invoking a write tool.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the returned data (identity and aggregated backend info) and states it only uses healthy backends. No contradictions or hidden side effects are indicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two efficient sentences. The first states the return values, and the second provides practical usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and no output schema, the description covers what the tool returns and its purpose. It could mention idempotency or read-only nature, but the context implies it is safe. Adequately complete given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema coverage is 100%. The description adds no parameter info, which is acceptable as there are none. Baseline for zero-param tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the caller's OAuth identity with specific fields listed (email, sub, pool, etc.) and aggregated whoami from healthy federated backends. This distinguishes it from siblings that list or read resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool before invoking write tools to know identity and capabilities. While it doesn't list when not to use it or alternatives, the context with sibling tools makes the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: listing resources, listing tickets, reading resources, reporting missing capabilities, and identity check. No overlap or ambiguity.
Most tools follow a 'verb_cortex_noun' pattern (list_cortex_resources, list_cortex_tickets, read_cortex_resource), but report_missing_capability lacks 'cortex' and whoami is a single verb, causing minor inconsistency.
5 tools is well-scoped for a gateway providing resource discovery, ticket management, and identity checking; each tool earns its place without bloat or deficiency.
The tool set covers all essential operations: discovering resources, reading them, filing tickets, viewing own tickets, and identity verification. No dead ends or missing functionality for the stated purpose.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Marketplace gateway: 100+ services and 1,400+ tools behind one MCP connection with unified auth
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/wellknownmcp/cortex-gateway'
If you have feedback or need assistance with the MCP directory API, please join our Discord server