Skip to content
Latest (currently 2026.9.0) has the newest features, bug fixes, and CVE patches of Solo Enterprise for agentregistry.

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Registry MCP server

Page as Markdown
Expose the Solo Enterprise for agentregistry catalog as a read-only MCP server so AI assistants, such as Claude Code and Codex, can discover and query registered agents, MCP servers, skills, prompts, models, plugins, deployments, and runtimes.
Solo Enterprise for agentregistry includes a built-in MCP bridge that exposes the registry catalog as a streamable HTTP MCP server. MCP clients, such as Claude Code or Codex, can connect to this MCP server and use catalog tools to discover agents, MCP servers, skills, prompts, models, plugins, deployments, and runtimes without leaving their AI assistant session.
Note
The MCP server is read-only. It does not invoke tools on cataloged MCP servers or proxy traffic to them. To add or update registry catalog items, you must continue using the Solo Enterprise for agentregistry UI, REST API, or arctl command line tool.
Authentication options for MCP clients

The registry MCP server supports the following authentication options for MCP clients. Regardless of the method that you choose, the registry MCP server enforces the same OIDC authentication and AccessPolicy RBAC mechanisms as the registry REST API, UI, and arctl command-line tool.
OptionHow it worksWhen to use
Static auth headerYou extract a token from an active arctl session and pass it as a static Authorization header when registering the registry MCP server. Tokens expire when the OIDC session expires and must be refreshed manually.Use this approach for a quick and simple setup, when you need to connect MCP clients that do not support OAuth authentication, or in environments where the registry MCP server is not publicly exposed with an ingress gateway.
Interactive OAuthUse the config.mcpBridgeUrl Helm value to configure the registry MCP server URL. When this value is set, the registry MCP server serves RFC 9728 protected-resource metadata at <host>/.well-known/oauth-protected-resource/mcp, which lets MCP clients discover the configured IdP automatically. If your MCP client supports OAuth authentication, it automatically opens a browser during the OAuth login process and redirects the user to the IdP login page for authentication.

MCP clients can also handle token refresh automatically. To support this process, your IdP must be served on an HTTPS endpoint, because MCP clients refuse to send token requests to a plain HTTP address.		Production environments where the registry server is exposed with an ingress gateway, your IdP is served over HTTPS, and MCP clients support OAuth authentication, such as Claude Code or Codex.
Available registry MCP server tools

The following tools are exposed on the registry MCP server and can be used in an AI assistant session.
ToolDescription
list_agents, get_agentList or retrieve agents from the catalog.
list_servers, get_serverList or retrieve MCP servers from the catalog.
list_skills, get_skillList or retrieve skills from the catalog.
list_prompts, get_promptList or retrieve prompt templates from the catalog.
list_models, get_modelList or retrieve model configurations from the catalog.
list_plugins, get_pluginList or retrieve agent plugins from the catalog.
list_deployments, get_deploymentList or retrieve deployments.
list_runtimes, get_runtimeList or retrieve the Runtime resources that agents and MCP servers are deployed to.
registry_healthCheck the health of the registry MCP server.
registry_versionGet build information for the registry.
Before you begin

  1. Set up an OIDC provider. This guide assumes that you installed Keycloak. Make sure to follow the General setup tab to install Keycloak with the required realm settings, clients, and secrets.
  2. Install Solo Enterprise for agentregistry.
  3. Log in to the registry. Choose between the interactive device authorization and the static username and password credential flow.
    Use this flow for interactive logins from a terminal. The CLI uses the ar-cli-interactive public client and starts a device authorization grant flow that prints a URL and a one-time code for you to approve in a browser.
    1. Configure the CLI to use the Keycloak issuer and ar-cli-interactive client. Then, log in to Solo Enterprise for agentregistry.
      export OIDC_ISSUER=$KEYCLOAK_ISSUER
export OIDC_CLIENT_ID=ar-cli-interactive
arctl user login
      Example output:
      To complete the login process, please:
 1. Open: http://172.18.0.13:8080/realms/agentregistry/device
 2. Enter the code: SYSQ-SNSP
 - or go to: http://172.18.0.13:8080/realms/agentregistry/device?user_code=SYSQ-SNSP

    2. Open the URL in a web browser and log into Keycloak with the admin-user username and password password. Confirming the code in the browser tells Keycloak to issue an access token for the CLI session. After authorization is complete, the CLI stores the token in your system keychain so you do not have to log in again until it expires.
    Use this flow for scripted logins where a specific user identity is required in CI/CD pipelines. The CLI uses the ar-cli-password public client and exchanges a username and password directly for an access token.
    1. Log in to Solo Enterprise for agentregistry with the admin-user/password credentials.
      export OIDC_ISSUER=$KEYCLOAK_ISSUER
arctl user login \
  --oidc-flow=password-credentials \
  --oidc-client-id=ar-cli-password \
  --oidc-username=admin-user \
  --oidc-password=password
    2. Save the access token in the ARCTL_API_TOKEN environment variable.
      export ARCTL_API_TOKEN=$(arctl user info --show-tokens | jq -r .access_token)
  4. Optional: Follow the Agents, MCP servers, or Skills guides to add sample agents, MCP servers, and skills to the registry catalog. After you connect to the registry MCP server, you can use its tools to list and see details about these artifacts.
Step 1: Expose the registry MCP server

The registry MCP server listens on port 31313 of the registry server pod.
  1. Port-forward the registry server on port 31313. The registry MCP server port is separate from the UI and REST API port (12121), so that you can run both port-forwards at the same time.
    kubectl -n agentregistry-system port-forward svc/agentregistry-enterprise-server 31313:31313
  2. Save the registry MCP server address as an environment variable. Include the /mcp path. The registry MCP server answers MCP requests on any path on port 31313, but the path that you use here is echoed in the protected-resource metadata URL for OAuth discovery. When you later use the arctl configure command to connect an MCP client to your registry MCP server, the command expects the path to include the /mcp suffix.
    export MCP_SERVER_URL=http://localhost:31313/mcp
Note
If you serve the registry server on a public URL by using an ingress gateway, you can expose the registry MCP server by routing requests to the /mcp path and mcp named port. The mcp port automatically targets port 31313 on the registry server. For example, your registry MCP server address might look similar to https://registry.example.com/mcp.
If you also want MCP clients to use interactive OAuth, you must add a route for the OAuth discovery endpoint, such as https://registry.example.com/.well-known/oauth-protected-resource/mcp and the endpoint that your registry MCP server is exposed on, such as https://registry.example.com/mcp. For a full example, see Expose the registry over HTTPS.
Step 2: Enable OAuth discovery for MCP clients (optional)

If your MCP client supports OAuth authentication, you can upgrade your Solo Enterprise for agentregistry Helm installation to set the registry MCP server address in the config.mcpBridgeUrl field to the MCP_SERVER_URL value that you retrieved earlier. When this value is set, the registry MCP server serves RFC 9728 protected-resource metadata at <host>/.well-known/oauth-protected-resource/<suffix-from-MCP_SERVER_URL>. Note that any suffix path that you include in the MCP_SERVER_URL is appended to the URL. For example, if you set MCP_SERVER_URL=http://localhost:31313/mcp, the protected-resource metadata is served at <host>/.well-known/oauth-protected-resource/mcp.
You can optionally set config.mcpBridgeAudience to restrict which tokens the registry MCP server accepts. When your IdP issues a token, it includes an aud (audience) claim that lists the services the token is valid for. Setting the config.mcpBridgeAudience field tells the registry MCP server to reject any token that does not include this value in its aud claim. This way, you can prevent a token that is issued for another service, such as the REST API, from being reused against the registry MCP server.
Note
This step is only required when you want MCP clients to complete OAuth authentication interactively. If you use a static auth header to authenticate with the registry MCP server, skip this step and continue with Step 3: Connect an MCP client.
For more information, see Authentication options for MCP clients.
helm upgrade -i agentregistry \
  oci://us-docker.pkg.dev/solo-public/agentregistry-enterprise/helm/agentregistry-enterprise \
  --namespace agentregistry-system \
  --reuse-values \
  --set config.mcpBridgeUrl="${MCP_SERVER_URL}"  
Helm valueDescription
config.mcpBridgeUrlThe external URL MCP clients use to reach the registry MCP server. Enables protected-resource metadata for interactive OAuth flows. When unset, interactive OAuth is disabled and you must authenticate with the registry MCP server by using a static auth header.
config.mcpBridgeAudienceOptional: The expected aud claim in tokens that are presented to the registry MCP server. When unset, no audience check is performed.
Step 3: Connect an MCP client

Choose your MCP client and connect it to the registry MCP server. Follow the auth pattern that you set up in the previous steps.
For Claude Code, Cursor, Visual Studio Code, and Kiro, you can generate the client’s MCP configuration file with the arctl configure command instead of registering the server by hand. The command merges its entry into the client’s existing configuration file, or creates the file if it does not exist yet, and always names the server entry arctl. Note that the command cannot set the OAuth client ID that the interactive OAuth flow requires. If you plan to use interactive OAuth, you must add the server manually.
The following table shows the clients that are supported out of the box.
ClientCommandConfiguration file
Claude Codearctl configure claude-code.mcp.json
Cursorarctl configure cursor.cursor/mcp.json
Visual Studio Codearctl configure vscode.vscode/mcp.json
Kiroarctl configure kiro.kiro/settings/mcp.json
Include the --url flag so that the command uses your registry MCP server address. Without this flag, the command defaults to the agentgateway port (21212) instead of the registry MCP server port (31313). To authenticate with a static auth header, add the --token-env flag with the name of the environment variable that holds your token, such as --token-env ARCTL_TOKEN. Only the name of the variable is written to the configuration file, never the token itself.
Codex does not have an arctl configure command. To connect Codex, follow the steps in the Codex section.
Claude Code

  1. Get a token from your active arctl session and save it in an environment variable.
    export ARCTL_TOKEN=$(arctl user info --show-tokens | jq -r .access_token)
  2. Generate the MCP configuration file for Claude Code. The command writes a .mcp.json file to the current directory, which scopes the registry MCP server to that project. The file references the ARCTL_TOKEN environment variable instead of storing the token value, so you must start Claude Code from a shell where that variable is set.
    arctl configure claude-code --url "${MCP_SERVER_URL}" --token-env ARCTL_TOKEN
    Example output:
    Configured Claude Code

    Alternatively, you can register the server directly with the following command. Because this command expands ARCTL_TOKEN immediately, the token value itself is stored in the Claude Code configuration.
    claude mcp add --transport http agentregistry "${MCP_SERVER_URL}" \
  --header "Authorization: Bearer ${ARCTL_TOKEN}"
  3. Verify that the server is registered. If you used arctl configure, the server is named arctl instead of agentregistry.
    claude mcp list
    Example output:
    agentregistry: http://localhost:31313/mcp (connected)

  4. When the token expires, re-run steps 1–2 to refresh the token.
Important
This method requires the OAuth discovery setup in Step 2, and your IdP must be served over an HTTPS endpoint. MCP clients refuse to send token requests to a plain HTTP address. The Keycloak instance from the Before you begin section is served over plain HTTP on a load balancer address, so interactive OAuth cannot complete against it. To test the registry MCP server in a local environment, use the Static auth header method instead.
  1. Register the registry MCP server with the ar-mcp-client Keycloak client.
    claude mcp add --transport http agentregistry "${MCP_SERVER_URL}" \
  --client-id ar-mcp-client
  2. Log in interactively. Claude Code reads the registry MCP server’s OAuth discovery metadata, opens a browser window to your IdP, and stores the resulting token after a successful login.
    claude mcp login agentregistry
  3. Verify that the server is registered.
    claude mcp list
    Example output:
    agentregistry: http://localhost:31313/mcp (HTTP) - ✔ Connected

Cursor, Visual Studio Code, and Kiro

The following steps use Cursor as an example. To configure a different client, replace cursor with vscode or kiro.
  1. Get a token from your active arctl session and save it in an environment variable.
    export ARCTL_TOKEN=$(arctl user info --show-tokens | jq -r .access_token)
  2. Generate the client’s MCP configuration file.
    arctl configure cursor --url "${MCP_SERVER_URL}" --token-env ARCTL_TOKEN
    Note
    To generate the client configuration for Visual Studio Code or Kiro, replace cursor with vscode or kiro.
    Example output:
    Configured Cursor AI Editor

  3. Reload or restart the client so that it picks up the new configuration file, and verify that the arctl MCP server is connected.
  4. When the token expires, re-run steps 1–2 to refresh the token.
Note
Cursor and Kiro read the token from the ARCTL_TOKEN environment variable each time they connect, so you must start these clients from a shell where the variable is set. Visual Studio Code does not read the environment variable. Instead, it prompts you for the token the first time it connects and stores the token in its own secret storage.
Important
For these clients, interactive OAuth is possible only if your IdP permits dynamic client registration. Unlike claude and codex, the Cursor, Visual Studio Code, and Kiro clients do not support pointing an MCP server at a pre-registered OAuth client, such as the ar-mcp-client Keycloak client that you create in Before you begin. The MCP client must instead register itself with your IdP. Because the Keycloak realm from the Before you begin section does not permit dynamic client registration, use the Static auth header method with the setup in this guide.
To use interactive OAuth with these providers, your IdP must permit dynamic client registration. The following steps demonstrate how to set up your IdP and Cursor to support an interactive OAuth.
  1. Make sure that your IdP is served on an HTTPS endpoint, and that you completed the OAuth discovery setup in Step 2. For more information about how to serve your IdP over HTTPS, see your IdP’s documentation.
  2. Allow MCP clients to register themselves with your IdP. In Keycloak, the anonymous Trusted Hosts client registration policy controls this behavior. The following commands find that policy in your realm and allow local MCP clients to register.
    export KEYCLOAK_TOKEN=$(curl -s \
  -d "client_id=admin-cli" -d "username=admin" -d "password=admin" \
  -d "grant_type=password" \
  "${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token" \
  | jq -r .access_token)

export POLICY=$(curl -s -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" \
  "${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/components?type=org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy" \
  | jq '.[] | select(.providerId=="trusted-hosts" and .subType=="anonymous")')

echo "${POLICY}" | jq '.config = {
    "trusted-hosts": ["localhost","127.0.0.1"],
    "host-sending-registration-request-must-match": ["false"],
    "client-uris-must-match": ["true"]
  }' \
  | curl -s -X PUT -H "Authorization: Bearer ${KEYCLOAK_TOKEN}" \
    -H "Content-Type: application/json" -d @- \
    "${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/components/$(echo "${POLICY}" | jq -r .id)"
    MCP clients start a local server to receive the OAuth callback, which is why localhost and 127.0.0.1 must be trusted. To let MCP clients register from other hosts, such as a remote development environment, add those hosts to the trusted-hosts list.
  3. Generate the client’s MCP configuration file. Because you omit the --token-env flag, no Authorization header is written to the file.
    arctl configure cursor --url "${MCP_SERVER_URL}"
    Example output:
    Configured Cursor AI Editor

  4. Reload or restart the client so that it picks up the new configuration file. The client registers itself with your IdP, opens a browser window to the IdP login page, and stores the resulting token after a successful login.
  5. Verify that the arctl MCP server is connected.
Note
With dynamic client registration, each MCP client that connects registers a new client in your IdP. Over time, this can create a large number of clients that you must clean up. Consider this trade-off before you enable dynamic client registration in a production environment.
Codex

  1. Get a token from your active arctl session and save it in an environment variable.
    export ARCTL_TOKEN=$(arctl user info --show-tokens | jq -r .access_token)
  2. Register the registry MCP server in Codex.
    codex mcp add agentregistry --url "${MCP_SERVER_URL}" \
  --bearer-token-env-var ARCTL_TOKEN
  3. Verify that the server is registered.
    codex mcp list
  4. When the token expires, re-run steps 1–2 to refresh the token.
Important
This method requires the OAuth discovery setup in Step 2, and your IdP must be served over an HTTPS endpoint. MCP clients refuse to send token requests to a plain HTTP address. The Keycloak instance from the Before you begin section is served over plain HTTP on a load balancer address, so interactive OAuth cannot complete against it. To test the registry MCP server in a local environment, use the Static auth header method instead.
  1. Register the registry MCP server with the server URL.
    codex mcp add agentregistry --url "${MCP_SERVER_URL}" \
  --oauth-resource "${MCP_SERVER_URL}"
  2. Log in interactively. Codex reads the registry MCP server’s OAuth discovery metadata, opens a browser window to your IdP, and stores the resulting token after a successful login.
    codex mcp login agentregistry --scopes openid,profile
  3. Verify that the server is registered.
    codex mcp list
    Example output:
    agentregistry: http://localhost:31313/mcp (HTTP) - ✔ Connected

Step 4: Verify catalog access

Verify that you can access the tools that are exposed on the registry MCP server to browse the registry catalog and view the AI artifacts that you added to it.
  1. Open your preferred AI assistant, such as Claude Code and ask it to list all the agents in the registry catalog.
    Example prompt:
    List all agents in the registry catalog.
  2. Verify that the assistant uses the list_agents tool to look up the agents that are registered in the registry catalog. The assistant returns a table that looks similar to the following.
    Example output in Claude Code:
    List all agents in the registry catalog.                                                                                                      
Called agentregistry (ctrl+o to expand)

⏺ There is 1 agent in the registry catalog:

  ┌─────────────┬────────────────────────────────────┐
  │    Field    │               Value                │
  ├─────────────┼────────────────────────────────────┤
  │ Name        │ myagent                            │           
  ├─────────────┼────────────────────────────────────┤
  │ Tag         │ latest                             │
  ├─────────────┼────────────────────────────────────┤
  │ Description │ myagent agent                      │
  ├─────────────┼────────────────────────────────────┤
  │ Model       │ gemini-2.5-flash (Gemini provider) │          
  ├─────────────┼────────────────────────────────────┤
  │ Framework   │ ADK (Python)                       │
  ├─────────────┼────────────────────────────────────┤
  │ Image       │ localhost:5001/myagent:latest      │
  ├─────────────┼────────────────────────────────────┤
  │ Created     │ 2026-07-28                         │
  └─────────────┴────────────────────────────────────┘

  3. Continue listing other AI artifacts, such as MCP servers and skills, or view the deployed instances.
Note
The catalog view is scoped to the user’s AccessPolicy. If you expect to see an artifact but it does not appear, confirm that your user’s role has registry:read permission for that artifact. For more information, see Restrict registry access.
Licensing