Connect your AI assistant

Let your AI assistant create workspaces, create test agents and MCP servers inside them, update their responses, and register existing endpoints in Agent Explorer. MCP is the connection that lets your assistant use these Explorer actions.

Describe what you need → Your assistant configures it → Open and test it in Explorer.

What can I do?

The assistant interprets your request. Agent Explorer validates and saves the structured configuration using the same engines as the visual editors. You can continue editing here. Registering an endpoint does not deploy a new service or run business operations.

Get connected

1. Open Settings → MCP access. Choose an assistant that supports remote MCP connections, such as Codex, Claude or another compatible client.
2. Copy the endpoint URL into your assistant's MCP server or connector settings. Use OAuth if offered and supported by your client, or create a management key with the permissions your task needs. Save keys in the client's secure credential settings, never in chat messages.
3. Reconnect the assistant so it discovers the available actions. Ask “What can you do with Agent Explorer?”, then try an example below. Follow the returned Explorer link to review and test the result.

Setup and authentication support vary by client. The settings page shows whether MCP access and OAuth are enabled on this installation. A copied URL or key does not by itself confirm a successful connection.

Prompts to try

Create a workspace with mocks

Create a personal workspace called Weather Lab, then add a mock weather agent and a mock weather MCP server to it. Return the workspace and resource links so I can test them.

Permissions: View mocks + Create workspaces + Create mocks.

Create a mock

Create a mock weather MCP server in my personal Explorer with a weather tool that accepts a city and returns a sample forecast. Return the Explorer link so I can test it.

Permissions: View mocks + Create mocks.

Update behavior

Find my support mock agent in Explorer. Update its default response to reply ‘How can I help?’ when a message contains ‘help’, and ‘Please describe your question’ otherwise. Preserve its other settings. If there is more than one match, ask me which agent to update.

Permissions: View mocks + Edit mocks.

Register an endpoint

Register this existing endpoint in my personal Explorer: [URL]. Detect whether it is an A2A agent or an MCP server and return its Explorer link. If discovery fails, ask me before registering it without verification.

Permissions: Register endpoints.

Replace [URL] with the endpoint you want to register. The update example needs an existing support mock agent. Examples remain available with Copy prompt buttons in Settings, even after you connect; copying makes no changes.

For mock creation and editing, grant View mocks as well as the relevant write permission so the assistant can inspect schemas, validate definitions and read current revisions. To create a workspace and populate it in one prompt, grant Create workspaces and Create mocks too. Add View mocks to Register endpoints if you want the assistant to find a team workspace.

How access works

You choose the assistant's permissions. Personal ownership is the default; team access follows your current membership. You can revoke a management key at any time without stopping mocks already created with it.

New mock endpoints are public by default. Enable key protection in their Configure screen when needed. Management keys authorize changes in Explorer; they are separate from credentials used to invoke mocks or protected remote services.

The server publishes instructions during connection and a getting-started MCP resource at agent-explorer://guides/getting-started. Compatible clients can read this guide for supported actions, example prompts and editing workflows. Client support for presenting this guidance varies; this page and Settings remain available.

Connection reference

The management endpoint is /api/management/mcp, using Streamable HTTP. Availability depends on the installation's feature flag. Find the exact URL and status in Settings → MCP access.

Connect with OAuth

Add the management URL as a remote MCP server in your assistant and choose OAuth. Follow Clerk's hosted sign-in and consent screen. Grant only the permissions you intend to use. Refusing consent must leave the assistant disconnected. Clients use authorization-code flow with PKCE (S256); refresh and revocation are handled by Clerk.

The server publishes discovery at /.well-known/oauth-protected-resource/api/management/mcp, with the configured Clerk authorization server. It also exposes /.well-known/oauth-authorization-server for older clients.

OAuth must first be configured by the installation administrator using the checklist below. OAuth connections remain disabled until that setup is verified. A browser login alone does not authorize management calls.

Connect with a management key

1. Open Settings → MCP access and select Create key.
2. Name the key after the assistant, choose permissions and an expiry (7, 30, 90 or 365 days, or Never). Keys set to Never remain valid until revoked; the default is 30 days.
3. Copy the full key immediately. It is displayed once and only its hash is stored.
4. Configure the assistant's secure credential field to send Authorization: Bearer YOUR_KEY to the management URL.

Keys have the aem_ prefix. They are separate from mock invocation keys. Settings shows expiry, status and last use. Revoking a key blocks new management requests immediately. Mocks already created with the key keep working.

Use the same endpoint with Codex, Claude or another compatible client. Client configuration varies: some clients accept a Bearer token directly; others use an environment variable or secure credential store. Keep keys out of prompts and source control.

Permissions and destinations

Permissions do not override ownership. Team access is checked against current membership for every operation, including retried writes. Removing a user from a team removes their management access to its resources.

Creation defaults to personal ownership. An explicit team owner or workspace selects a different destination. A workspace's owner is used if an owner is omitted; contradictory destinations are rejected. Use list_workspaces to find destinations and list_mocks to search and paginate.

To create a new workspace and mocks in one prompt, the assistant calls create_workspace with a unique requestId and uses the returned id as workspaceId in subsequent create_mock_agent or create_mock_mcp_server calls. Each write needs a different requestId. These calls are not a single transaction: if a later mock creation fails, the workspace and any earlier mocks remain. The assistant should report what succeeded and what still needs attention. Existing management keys and OAuth grants need the new workspaces:create permission before this tool appears.

New mock invocation endpoints are public by default. Successful results include requireApiKey: false, runtime/discovery URLs, an Explorer link and a revision. To protect a generated mock, open its existing Configure screen and enable invocation-key protection. Management authentication does not make invocation private.

Tools

Tools accept JSON objects, not JSON encoded in strings. Start with get_definition_schema for the authoritative schema. Responses can use echo, fixed, conditional or failure presets, or full executable flow graphs. Generated flows have deterministic positions when layout is omitted and open in Flow Builder. Newly supplied graphs must be acyclic, have valid branches and references, and terminate. Unrelated edits preserve untouched legacy graphs.

Whole-mock deletion, ownership transfers, team administration, credential management and invoking real business operations are outside this interface.

Register an existing endpoint

Grant Register endpoints (connections:create) when creating a management key. Existing mock-only keys do not gain this permission automatically; create a new key with the permissions you need. OAuth clients must also be granted the new scope. Add View mocks if the assistant needs to discover available workspaces.

Ask: “Register https://example.com/mcp in my personal Explorer and detect its protocol.” The assistant calls connect_endpoint with requestId and url. Optional name, owner and workspaceId work like mock creation. Registration creates a real Explorer project or MCP connection, never a mock. The result includes its Explorer link, registered URL, owner and verification report. list_mocks and get_mock continue to cover mocks only; open the returned link to manage the new connection.

By default, protocol: auto and verify: true try AgentCard discovery, then MCP Streamable HTTP initialization. No agent messages, tools, resources or prompts are invoked. “Verified” confirms discovery only, not invocation permissions or remote behavior. Checks are limited to public addresses in hosted Explorer; loopback addresses are also supported when Explorer runs locally. Redirects are not followed: supply the final URL. Discovery has a 20-second overall deadline and a 1 MiB response limit.

If authentication, a private network or unavailable discovery prevents detection, explicitly choose protocol: a2a or protocol: mcp and verify: false. This saves an unverified connection without contacting the server. Configure credentials through the returned Explorer page. Do not put secrets in the URL; management credentials are never forwarded to the endpoint.

Each registration requires a requestId. Retry with the same ID and arguments to recover the original result; a changed request with that ID is rejected. The connection, workspace association, receipt and audit record are saved atomically. Current team membership is checked on creation and replay.

Discover template variables

Before constructing a response, ask the assistant to call get_definition_schema. Its interpolation object contains syntax rules, typed built-in variables for A2A and MCP, examples, and a per-node list of fields that accept templates. Field paths are relative to node data. The same catalog powers Flow Builder's Variables panel and MCP payload hints.

• A2A: {{inputText}}, {{agentName}}, {{skillName}}, {{taskId}}, and fields of the full input message.
• MCP tools: {{toolName}} and argument paths such as {{toolArgs.city}}, determined by that tool's inputSchema.
• MCP prompts: {{promptName}} and paths such as {{promptArgs.topic}}, determined by that prompt's declared arguments.
• MCP resources: {{resourceUri}}. All MCP flows also have {{mcpServerId}}.
• Custom values: declare flow.variables for initial values, or use Set Variable before the value is needed. {{response}} contains text accumulated by previous Set Payload nodes.

Set Payload content, condition operands, Set Variable values, log/error messages and A2A End status messages accept interpolation. Delay duration, MIME types, node labels and notes do not. Use dot notation for nested fields and array indices, for example {{input.parts.0.text}}. Expressions, function calls, filters and bracket notation are unsupported. Objects become JSON text, but strings are not automatically escaped for insertion into a larger JSON document. Missing or null values leave the original placeholder unchanged.

validate_mock_definition checks compiled presets and full flows and returns warnings with the response target, node and field. Warnings identify unknown variables, undeclared capability argument paths, wrong capability contexts and variables that may not have been assigned on every incoming branch. These are conservative static checks: complex JSON Schemas and dynamic nested objects cannot always be resolved. Warnings do not block saving or change runtime behavior; review them before creating the mock. A declaration with a default can supply a value on every branch.

Example creation

Ask your assistant: “Create a mock weather MCP server with a weather tool accepting a city and always returning Sunny.” It can call create_mock_mcp_server with:

{
  "requestId": "weather-demo-01",
  "definition": {
    "name": "Weather demo",
    "capabilities": {
      "tools": [{
        "name": "weather",
        "description": "Get a sample forecast",
        "inputSchema": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }],
      "resources": [],
      "prompts": []
    },
    "responses": [{
      "target": "tool:weather",
      "response": { "preset": { "kind": "fixed", "text": "Sunny" } }
    }]
  }
}

For a direct HTTP check, initialize MCP, then send a tools/call request with that object under params.arguments. Use Content-Type: application/json, Accept: application/json, text/event-stream, MCP-Protocol-Version: 2025-03-26, and the Authorization header. Standard MCP clients handle initialization and protocol negotiation for you.

Editing and conflict recovery

Read get_mock first. Include its revision as expectedRevision when updating. Use explicit add, remove, rename or replace operations for skills and capabilities, and target individual responses. Other fields, custom flows and legacy fallback behavior are preserved.

Every write requires a unique requestId. Retry an uncertain request using the exact same identifier and arguments. Reusing an identifier with different arguments is rejected. Receipts are scoped to the user and management credential; renewing the same OAuth client's access token preserves retry identity. Switching keys or OAuth clients starts a separate receipt namespace.

If an update returns REVISION_CONFLICT, reread the mock, reconcile your intended change with the latest state and submit a new requestId with the fresh revision. Never automatically overwrite the newer configuration. Creation transactions roll back together if any project or workspace write fails.

Installation administrator setup

The server is disabled by default. Apply scripts/migrate-management-mcp.ts to an explicitly selected database before enabling it. The migration creates management tables and indexes and is safe to repeat. Rerun it on installations created before the Never expiration option: it makes management key expiration nullable while preserving existing keys and their expiration dates. Existing mock data, invocation URLs and invocation keys remain unchanged.

Configure these server environment variables:

In Clerk's OAuth application settings:

• Create and advertise mocks:read, mocks:create, mocks:update, connections:create, workspaces:create, and assign the intended scopes to registered clients.
• Enable JWT access tokens, the aud claim derived from the resource parameter, and mandatory PKCE S256. Tokens without the exact management resource audience are rejected. The installed SDK omits audience from introspection results, so the server uses Clerk's documented Backend API to verify it and current revocation status.
• Use Clerk's hosted consent screen. Configure explicit client registrations and redirect URIs, or enable dynamic client registration for clients that require it. CIMD beta is optional and is not required by this server.
• For dynamic clients that omit scopes, configure suitable default management scopes; start with read access and grant writes deliberately.
• Run npx tsx scripts/check-management-oauth.ts with the intended environment. This read-only check reports required settings without printing credentials. A successful configuration check does not replace a real consent/renewal/revocation test.

Before enabling OAuth, test Codex and Claude connections, refused consent, refresh, expiry, revocation, wrong issuer/resource and missing permissions. Verify generated mocks in Explorer and invoke both A2A versions and MCP capabilities. Keep OAuth off if any release gate remains unverified.

Requests are bounded to 256 KiB. Rate limits are shared through the database across application instances; HTTP 429 includes Retry-After. Audit records contain identity, operation, target and outcome, without raw keys, prompts or definition payloads. Write receipts retain the safe result needed for retries, including the mock definition; apply your installation's data-retention policy to them.

Turning off MANAGEMENT_MCP_ENABLED stops management calls while leaving existing mocks operational. Apply the additive migration independently; it does not change either feature flag.