An external tool can ask Nebula about an engagement and prepare a proposal for a person to review. It cannot confirm, certify, pay or apply a change. Nebula still checks the person's current membership, the selected company, the engagement's sharing rules and the existing question allowance.
Before connecting
Use a remote MCP client that supports OAuth with a pre-registered client ID. Connections are available only on engagements enabled for the owner-controlled rollout. A registered client is not an endorsement of a service, and registration does not grant it access.
Open Settings > Agent connections as an organisation owner or administrator. Get the exact OAuth callback address from your tool, register that address and copy the client ID. Enter the client ID and the MCP address shown in Nebula into your tool. No client secret is issued for this public-client, PKCE flow.
When the tool opens Nebula, check its name and full callback address, choose one engagement, and approve the permissions. Do not copy your Nebula session cookie into another tool. Access expires within one hour; start a fresh authorisation when it expires. You can revoke the connection immediately from Agent connections.
What the permissions mean
engagement:read: list the approved engagement and ask questions about its available record. Questions themselves are retained on that engagement.engagement:propose: also prepare a proposal for human review. This permission does not authorise the proposed effect.
The tools are nebula_engagements, nebula_ask and, with proposal permission, nebula_propose. Questions require an engagement ID, message and stable idempotency key. Reuse the key and returned thread ID when retrying. Do not resend the same question under a new key.
Permission and receipts
Open Authority and receipts beside your tool in Agent connections. The permission record names the engagement, allowed actions and expiry. Activity receipts distinguish an engagement list, a recorded question, an answer, a proposal and a refused or interrupted request. Approving access alone is not evidence that a tool did any work.
Receipts remain available after expiry or withdrawal, subject to your current company and engagement access. They are private to the authorising organisation. A proposal receipt means a draft was prepared, not that its change was accepted or applied. These receipts are not blockchain seals or certifications.
Client implementation
The remote MCP endpoint is /api/harness/mcp. The public discovery documents are /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server on the same host. Follow the endpoints in those documents.
Send response_type=code, the registered client_id, its exact redirect_uri, a random state of at least 16 characters, code_challenge_method=S256, a SHA-256 PKCE challenge and the requested space-separated scopes. Both the authorisation request and token exchange must name the complete MCP endpoint as resource. Exchange the code within five minutes, using the original verifier. Codes are single-use. Send the returned token only in the Authorization: Bearer header, never in a URL. Refresh tokens and dynamic client registration are not offered.
Client callbacks must use HTTPS, except a local native client may use an exact HTTP loopback IP address. Wildcards, fragments and embedded credentials are refused. Only the account that registered a client can approve it. Changing a callback means registering a new client and revoking the old one.
The protocol follows MCP authorisation. This connection does not replace an integration's own provider consent or make every outside service available. Selected-file import, accounting observations and other provider paths keep their own source-selection and approval requirements.