Custom MCP

Custom MCP connects Minara to a remote tool server that you trust. Its tools join the Catalog after preflight. They stay disabled until you review and enable them.

Open Connectors → Add connectors → Add MCP server.

Add by URL

Use Add by URL for an HTTPS Streamable HTTP or SSE server. Enter:

Server name
Server URL
Optional note
Optional OAuth client ID
Optional OAuth client secret

The OAuth fields support three modes:

Input	Authorization mode
No client ID	OAuth discovery with CIMD or DCR and PKCE
Client ID only	Public client with Authorization Code and PKCE
Client ID and secret	Confidential client with code exchange in the Gateway

A client secret without a client ID is invalid. The secret is write-only. The Gateway encrypts it in the Gateway credential store. Minara does not return it through the API, diagnostics, export, or logs.

Custom configuration

Use Custom configuration for an HTTP or SSE endpoint with a custom icon, note, and non-sensitive public headers. This form rejects authorization, Bearer, API key, password, and secret headers. Use Add by URL when the server needs an OAuth client secret.

Import JSON or JSONC

The importer accepts mcpServers and servers maps. It previews all entries before saving. Duplicate names default to Skip. Choose Replace for an intentional replacement.

Remote entries may use HTTPS HTTP or SSE transports. The importer recognizes restricted stdio definitions that use npx, pnpm dlx, or uvx with a registry package. This release keeps stdio execution disabled unless the Gateway has a supported isolated runner. Preflight fails closed when the jail is unavailable.

JSON import rejects embedded secrets, authorization values, Bearer tokens, API keys, and passwords. Add a confidential OAuth client through Add by URL.

Preflight and tool review

Before save, Minara:

Normalizes the configuration.
Validates transport and network destinations.
Discovers OAuth metadata when required.
Initializes the MCP session and requests tools/list.
Shows each tool, schema, and risk.
Saves the configuration only after confirmation.

If any save step fails, Minara rolls back the new configuration and its new credential reference.

Tools start off and use Ask every time when enabled. A schema change pauses affected write tools until you review the new schema. Custom MCP tools cannot initiate arbitrary fund movements directly. x402 fees use a separate payment gate and require per-payment confirmation or a matching pre-authorization. Automation, Institution analysts, and sub-agents cannot call custom MCP tools.

Paid MCP with x402

An MCP server may return an x402 challenge in the MCP JSON-RPC error, while a direct remote HTTP or SSE server may also return 402 Payment Required. When it publishes a supported x402 exact USDC challenge, Minara:

Captures the challenge and binds it to the original MCP request.
Shows the merchant, amount, asset, and network.
Creates a payment proof with the managed wallet.
Retries the same MCP request once with that proof.

Install a paid server exactly like any other remote MCP. Do not add a wallet private key, payment signature, or transaction proof to its URL, headers, JSON configuration, or OAuth fields. Those proofs are short-lived and managed by the x402 payment flow.

The MCP JSON-RPC form works across MCP transports, including local stdio. HTTP header payment applies only to direct remote connections. A hosted broker using that form must forward PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE without replacing or hiding them. See x402 Payments.

Network restrictions

Remote MCP URLs must use HTTPS. Minara blocks URL credentials, query tokens, loopback, private, link-local, and cloud metadata destinations. It validates OAuth issuer, authorization, registration, token, and redirect endpoints separately. DNS changes during connection are checked again.

Custom MCP is MCP-only. Missing tools and runtime failures return a clear error. Minara does not route a custom action to REST.