MCP Connections¶

An MCP connection is a link to an outside tool server, such as GitHub or Slack. You add the connection once. Then each sandbox chooses which of its tools agents can use.

Add an MCP Connection¶

Open Workspace settings → MCP connections for one workspace. Open MCP connections in the organization sidebar to share it.

1. Select Add MCP connection. A sheet opens.
2. Enter a Name. Use lowercase letters, numbers and hyphens, up to 32 characters, for example my-mcp.
3. Under Type, select OAuth to sign in to the outside service, or Bearer token to paste a token.
4. In MCP connection endpoint, search the built-in catalog or pick Custom Server and enter the URL, for example https://example.com/mcp.
5. For Bearer token, enter the Token. For OAuth, AgentZ tries to find the OAuth settings from the URL.
6. Select Add connection. For OAuth, a popup opens and the button reads Waiting for OAuth.... Finish the sign-in there.

The table row shows Accepted, then Ready. The status Error means the connection is degraded.

Match the Authentication to the Server¶

• OAuth client credentials: enter Client ID and Client secret only when the server has no dynamic client registration endpoint.
• Advanced under OAuth: Issuer, Authorization endpoint, Token endpoint, Registration endpoint, Resource and Scopes. If you see Auto-discovery failed, enter these by hand.
• Advanced under Bearer token: Bearer token header name (default Authorization) and Bearer token prefix (default Bearer).
• Extra headers: static header key and value pairs. Use them only for values that are not secret.

Register the Callback URL When the Provider Needs It¶

AgentZ registers itself with providers that support dynamic client registration. For other providers, register this callback URL in the provider's console. The URL is the address of the AgentZ app plus /mcps/oauth/callback. For the hosted app it is:

https://agentzharness.ai/mcps/oauth/callback

On a self-hosted install, use your own app address in place of agentzharness.ai.

Then enter the provider's Client ID and Client secret in the sheet.

Choose Tools per Sandbox¶

A connection gives no agent access until a sandbox exposes its tools. In the sandbox wizard, open the MCP step. See Create a sandbox for how to open the wizard.

1. Switch on the connection. The switch stays off until AgentZ finishes loading the tool list.
2. Expand the connection. Switch on each tool the sandbox may expose. Select at least one.
3. For each tool, set the consent with the button beside its switch. The tooltip shows Consent not required or Consent required. A newly switched-on tool starts as Consent not required.

The setting applies to one tool in one sandbox. You cannot delete a connection while a sandbox uses it.

Next Step¶

Secrets