Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.navisops.com/llms.txt

Use this file to discover all available pages before exploring further.

Navis Ops implements OAuth 2.1 with the authorization code + PKCE flow for AI clients that natively support MCP OAuth. With this method, you point your client at the Navis Ops MCP server URL, and it handles the entire authorization sequence — opening a browser, prompting you to sign in and approve access, and storing the resulting tokens. You never manually copy or paste a token. OAuth is the recommended authentication method for Claude Desktop and Cursor. If you’re using a client that doesn’t support the MCP OAuth flow, or you want a simpler setup, use an API key instead.

​
How the flow works

You do not need to implement this flow yourself — your MCP client does it automatically. This section describes what happens so you understand what each step means when your browser opens.
1

Client discovers the authorization server

When you add Navis Ops as an MCP server by URL, your client fetches the discovery document at /.well-known/oauth-authorization-server. This document tells the client where to send authorization requests and where to exchange tokens.
The discovery URL is public and predictable by design. Security comes from the bearer token, not URL secrecy.
2

Client registers itself

The client registers with Navis Ops using dynamic client registration (RFC 7591). Navis Ops issues a client_id for that client. This happens automatically and only once per client installation.
3

Your browser opens the consent screen

The client generates a PKCE code_verifier and code_challenge, then opens your browser to the Navis Ops authorization page. You sign in if needed, review the requested scopes, and click Approve or Deny.
4

Tokens are issued

If you approve, Navis Ops issues an access token and a refresh token. Your client stores both and uses the access token on every API request. The access token expires after one hour; the client uses the refresh token to get a new one automatically.
5

Client makes authenticated requests

From this point on, your client passes the access token as Authorization: Bearer <token> on every request to the MCP server. You do not need to interact with the token directly.

​
Discovery endpoint

MCP clients use the following endpoint to auto-discover the Navis Ops authorization server: 
/.well-known/oauth-authorization-server
The response includes all endpoints your client needs: authorization_endpoint, token_endpoint, registration_endpoint, and revocation_endpoint. You do not need to configure these manually — a compliant MCP client reads them automatically.

​
Scopes

Navis Ops supports two OAuth scopes:
ScopeWhat it grants
mcp:readRead access to all workspace data (projects, tasks, notes, calendar, goals, and more)
mcp:writeRead access plus the ability to create, update, and delete data
mcp:write implies mcp:read. There is no per-tool scope — mcp:write grants every write operation across the entire workspace. When your client prompts you to approve scopes, select mcp:read if you want the assistant to only read your data, or mcp:read mcp:write if you want it to create tasks, notes, events, and other records on your behalf.
If you approve only mcp:read and your AI assistant tries to call a write tool, it will receive a 403 Forbidden response with a message indicating the mcp:write scope is required. To fix this, disconnect and reconnect approving mcp:write.

​
Token details

  • Access token lifetime: 1 hour. Your client refreshes it automatically using the refresh token.
  • Refresh token lifetime: 30 days. After 30 days without use, you must reconnect.
  • Token format: Opaque bearer credentials — not JWTs. There is no client-side introspection. Do not attempt to decode or parse the token value.
  • Token prefix: OAuth access tokens use the mcpa_ prefix internally. API keys use nops_. You will see these in logs if you inspect network traffic.

​
Refresh token rotation

Every time your client uses a refresh token to get a new access token, Navis Ops issues a new refresh token and invalidates the old one. This is standard OAuth 2.1 refresh token rotation.
If a refresh token is used twice — for example, because an attacker obtained a copy of a rotated-out token — Navis Ops revokes the entire token family immediately. If this happens, your client loses access and you must reconnect by going through the authorization flow again. This is a security feature, not a bug.

​
Revoking access

To disconnect an OAuth client and revoke all its tokens:
  1. Go to Settings → Connected Apps.
  2. Find the client you want to disconnect.
  3. Click Disconnect.
This revokes all access tokens and refresh tokens for that client immediately. The next API request from that client returns 401 Unauthorized. Clients can also revoke tokens programmatically by posting to the revocation endpoint listed in the discovery document (per RFC 7009).

​
Supported clients

OAuth authentication works with any MCP client that implements the MCP OAuth 2.1 authorization flow with PKCE. Verified clients include:
  • Claude Desktop
  • Cursor
For clients that do not support MCP OAuth, use an API key with a static Authorization header instead.