Connecting

Two steps: tell your client where Nova lives, then sign in once so the client can act on your behalf.

Add the server

Add Nova as a remote MCP server in your client's settings. The URL is:

https://mcp.commcare.app/mcp

A typical config entry looks like:

{
  "mcpServers": {
    "nova": {
      "url": "https://mcp.commcare.app/mcp"
    }
  }
}

Field names vary by client — some use url, some endpoint; some need a transport marker. The URL is the same regardless. Check your client's docs for the exact wrapper.

If you're connecting Nova from an unattended pipeline, or from several parallel agents sharing one account, OAuth will fight you — sign-ins time out, parallel sessions invalidate each other, and you'll end up signing back in repeatedly. Use API keys instead — same scopes, no browser, no expiry surprises.

The first time your agent tries to use a Nova tool, your client opens a browser tab on commcare.app.

Review the permissions your client is asking for and click Allow. They're things like Read your apps and Create and edit apps on your behalf — see Manage access for the full list.

The browser tab closes (or shows a confirmation). Your client picks up the connection and your agent can call Nova from then on.

You only sign in once per client. The connection sticks until you revoke it.

If your client doesn't open the browser tab automatically, check its MCP logs — most clients print the sign-in URL there as a fallback.

CommCare HQ uploads

The HQ upload tool needs two things that aren't required for the rest of the surface:

HQ permissions on the connection. The consent screen has two HQ-specific rows — See your CommCare HQ project connection and Deploy your apps to CommCare HQ on your behalf. If your client requested them when you signed in, they're already part of the connection. If not, you'll need to sign out and back in once your client is configured to ask for them.
An HQ API key in Nova settings. Add the key on the Nova settings page. A key can reach more than one project space (Settings shows which); your agent picks the target per upload with the upload tool's domain argument.

If either is missing when the upload tool runs, the response carries a clear error your agent can pass back to you.

Verifying

Open Settings → Connected apps. Your client should appear in the list with the date it was connected, the permissions it has, and a button to revoke it.

Add the server

Sign in

CommCare HQ uploads

Verifying

On this page