Agent integration troubleshooting

Start with the failed command or connection. Keep its timestamp and correlation ID, then check the relevant section below. Do not copy credentials into diagnostic notes.

Discovery does not load

Confirm the portal URL, TLS trust, VPN, and private DNS. Open /.well-known/veriproof-configuration on that same origin. Do not substitute a guessed API URL.

Run veriproof auth status, then sign in again. Confirm the discovery document reports authentication.ready as true and the configured portal provider is available. V1 supports Microsoft Entra and Okta. Enter credentials only in the provider’s browser page.

The CLI starts a one-use callback listener on 127.0.0.1. Keep the CLI command running while you sign in. A successful browser page says VeriProof CLI is connected and tells you to return to the terminal. The listener then closes.

If the browser shows ERR_CONNECTION_REFUSED, the link is stale or the CLI process stopped. Start veriproof auth login again and use the newest link. Do not reuse an older callback URL.

If sign-in succeeds but the API rejects the token, confirm that the CLI profile uses the intended deployment. Ask an administrator to check the API’s issuer, audience, and CLI scope against the authorization service settings. Share the correlation ID with the administrator, not the token.

The CLI stores the long-lived refresh credential in the operating-system credential store. It does not persist the short-lived access token or place either value in the profile file.

MCP returns forbidden

The requested operation is not permitted for the current access scope. Use get_my_context to review the effective scope. Do not retry with an application key.

The MCP address is unclear

In the signed-in customer portal, open More tools → Agent tools. Copy the address shown there. For headless setup, read services.mcp from /.well-known/veriproof-configuration on the portal deployment. Do not derive an MCP hostname from a SaaS example.

If the client never opens sign-in, check that the MCP endpoint returns a 401 challenge with a resource_metadata address and that the protected-resource document names the exact MCP URL.

MCP reconnects after an idle stream

VeriProof v1 uses Streamable HTTP without server-initiated notifications. A standalone GET to the MCP endpoint returns 405 Method Not Allowed with the supported methods in the Allow header. This is expected; normal tool calls use POST.

If a client reports an HTTP 500 after an idle connection, confirm the deployment includes the stateless transport behavior above. Do not increase an Azure Functions request timeout to keep an unused event stream open.

If refresh-token rotation reports invalid_grant, close duplicate client processes and sign in once from the client you intend to keep. Do not run several clients that share one credential store through the same token refresh at the same time.

Ingest rejects a key

Confirm the key belongs to the selected application and deployment. Check its current status before replacing it. Treat an exposed key as compromised and revoke it promptly under your incident procedure. Run veriproof doctor to check deployment connectivity; it does not validate delivery of a new session.

Solana cannot be reached

Retry with an organization-approved RPC endpoint using --solana-rpc. A provider outage is not an integrity mismatch.

Azure SQL verification needs configuration

Confirm DefaultAzureCredential can sign in, private DNS resolves the database, and the identity can read the scoped proof row and run the database ledger verification procedure.

Record the diagnostic result

Keep the command name, timestamp, correlation ID, deployment URL, and redacted error together. Record what you checked and whether the result changed. Exclude credentials and evidence content before sharing the notes with an administrator.