Point an MCP Client at ExecWarden
Point an MCP client at /v1/mcp with Authorization: Bearer <agent-identity-token>. The visible tools are scoped to that identity, user, workspace, and policy.
| Client gets | A tool list filtered to the identity's active grants and the current workspace. |
|---|
| Client does not get | Raw provider OAuth tokens, package secrets, ungranted package actions, or uninspected remote MCP tools. |
|---|
| Risky calls | Tools in Ask mode return a pending approval response instead of executing immediately. |
|---|
OAuth for Client-Hosted Agents
OAuth-capable clients can use the same /v1/mcp Streamable HTTP endpoint without copying a long-lived bearer token. During authorization, choose the workspace and Agent identity the client should act through. OAuth scopes authenticate the MCP transport; canonical grants and approvals on that Agent identity still decide which tools the client can discover and invoke.
| Server URL | https://<gateway-host>/v1/mcp |
|---|
| Discovery | Clients use protected-resource metadata, authorization-server metadata, PKCE authorization, and token exchange endpoints exposed by the gateway. |
|---|
| Scopes | mcp:tools and mcp:resources open transport access. offline_access enables refresh-token rotation when the client requests it. |
|---|
| Authority | The selected Agent identity's live canonical grants decide actual provider, package, GitHub, sandbox, and imported MCP tool access. |
|---|
| Revocation | Revoke one connected OAuth client from the Agent identity detail page, or disable the identity to stop every client using it. |
|---|
| Verified smoke coverage | Codex CLI, Claude Code CLI, and OpenCode CLI are exercised in Docker against a live ephemeral gateway for MCP registration/config behavior. |
|---|
| Still manual | Full browser OAuth sign-in, exact per-client screenshots, Cursor Desktop validation, and any required static registration remain certification follow-up work. |
|---|
| Fallback | Clients without OAuth can still send Authorization: Bearer <agent-identity-token>; canonical grants and approvals apply the same way. |
|---|
Docs and examples
Agents can read ExecWarden docs, package examples, and capability-building guidance.
Package management
Management-capable keys can create, test, publish, disable, and delete packages.
Granted tools
Package actions and integrations appear only when the caller has policy for them.
Imported remote MCP tools
Workspace connectors can import remote tools from inspected MCP servers. Remote resources and resource templates are not proxied in public alpha.
Workflow management
Workflow-capable callers can create, inspect, update, trigger, and list workflow objects as that surface matures.
Remote MCP Connectors
Remote MCP connectors are workspace-owned credentials for another MCP server. Create the connector, inspect its tools/list inventory, then grant selected imported tools to an Agent identity. Agent identities never receive the provider token directly.
| Linear tested path | Use OAuth with endpoint https://mcp.linear.app/mcp. After the callback, inspect the connector, choose one low-risk tool such as an issue search/list tool, and grant that imported capability to an Agent identity. |
|---|
| Generic OAuth alpha | A provider-entered OAuth MCP endpoint must pass compatibility checks for protected-resource metadata, authorization-server metadata, dynamic client registration, PKCE S256, resource matching, the gateway-owned callback route, and refresh-token behavior when token responses expire. |
|---|
| Bearer token path | Bearer-auth remote MCP works for bring-your-own-token providers, but you own upstream token rotation and scope at the provider. |
|---|
| Unsupported today | ExecWarden imports remote MCP tools only. Remote resources and resource templates from the connected server are not brokered to clients. |
|---|
Treat the remote connector as the upstream credential and the Agent identity as the governed caller. Inspect first, grant one or two imported tools, then check Activity before adding broader write tools.
| Connector | Create and inspect the remote MCP connector before granting any imported tools. |
|---|
| Tool | Grant only the selected imported tool, such as an issue search/list capability from the inspected inventory. |
|---|
| Mode | Use Allow for low-risk reads; use Ask for writes or tools with unclear side effects. |
|---|
| Provider token | Keep the upstream token in the workspace connector. The Agent identity receives only the governed gateway capability. |
|---|
Remote MCP Lifecycle
| Disable connector | Workspace-local disable. Future gateway calls through that connector are denied for every Agent identity that still references it. This does not guarantee provider-side OAuth token revocation unless a provider-specific revocation hook exists. |
|---|
| Reconnect | Create a replacement connector, inspect its tools, then update Agent identities to grant the replacement connection id. Existing grants keep referencing the disabled connector until edited. |
|---|
| Revoke identity | Disables or expires one Agent identity token so that caller can no longer discover or invoke any granted tools. Other identities using the same connector are unaffected. |
|---|
| Revoke canonical grant | Removes an active canonical capability grant attached to an identity. It does not disable the connector itself. |
|---|
Package capability definitions use pkg:<workspace-segment>:<packageId>:<action>. For example, pkg:<workspace-segment>:linear-lite:viewer.get. The exposed tool name still replaces separators with underscores, producing pkg_linear-lite_viewer_get.
A package tool call may return before the provider action is complete because the package asked a person to decide or provide missing input. MCP clients should treat these as durable pauses, not transient tool errors.
pending_user_input | Generic request for resume, free text, single-choice, or multi-choice input. The caller receives a pending input id and should wait for the workspace user-input flow to answer it. |
|---|
pending_approval | Approval shape for approve/reject requests. Approval polling and approval UI use the same request id, and the answer is the approval decision for the selected followup action. |
|---|
| After answer | ExecWarden wakes the source session and, when configured, runs the same-package followup under the source policy. The client can continue from the resumed session context. |
|---|
| Next question | Use Gateway Capabilities for concrete grant scope, or Capability Packages when an internal API needs to become a governed tool. |
|---|