Skip to main content

MCP Connector for External AI Assistants

Navaid's remote Model Context Protocol (MCP) connector lets a compatible external AI assistant work with the connected user's authorised Navaid data through OAuth 2.1.

This is a feature-gated integration, not a public anonymous API.

Requirements​

  • The MCP connector feature must be enabled. System Admins can test while the general flag is off.
  • The external client must support a remote Streamable HTTP MCP server and OAuth.
  • The user needs a Navaid account and active company membership.
  • The deployment's OAuth server and consent redirect must be configured.
  • You need the canonical connector URL from the Navaid administrator.

The URL has this form:

https://<your-navaid-supabase-project>/functions/v1/mcp

Use the exact environment URL supplied by the administrator. Do not substitute a frontend application URL. A trailing slash is accepted, but keeping the canonical URL avoids client resource-matching problems.

Connect​

The labels differ by external client, but the sequence is:

  1. Open the client's connector or integrations settings.
  2. Add a custom remote MCP server.
  3. Enter the canonical Navaid MCP URL.
  4. Start authorisation.
  5. Your browser opens Navaid's consent flow.
  6. Sign in with passwordless authentication if required.
  7. Review the client name, signed-in email, identity scopes, and the Navaid access explanation.
  8. Select Approve or Deny.
  9. Return to the external client after redirect.

An already-approved authorisation can return directly to the client without showing the consent page again.

Approve only clients you trust

The identity scopes shown by OAuth do not by themselves describe every MCP tool. Read What this allows: the client can act as you within Navaid, including supported writes.

Available read tools​

ToolResult
list_companiesCompanies available to the connected account.
get_maturity_summaryAssessed dimensions, levels, coverage, and weakest areas.
get_dimension_detailLevel, confidence, rationale, and relevant open tasks for one dimension.
list_tasksCompany tasks, optionally filtered by status.
list_sessionsCompany session list.
get_session_summaryStored output for one session.
get_company_knowledgeCompany facts and learnings.

Read access is limited to active company memberships. System Admin behaviour follows the platform-wide role.

Available write tools​

update_company_facts​

Updates supported company fact fields. It is restricted to:

  • Company Admin;
  • Consultant; and
  • System Admin.

Changes are versioned in company-profile history and attributed to the connected user. Empty text is not accepted as a way to clear a fact; use the web application's company-knowledge workflow for intentional clearing.

complete_task​

Marks a task completed for an active company member.

dismiss_task​

Dismisses a task for an active company member.

The external client—not Navaid's in-app Aida dialog—controls how it asks for confirmation before calling a write. Review the client's proposed tool call.

Task completion still does not force a maturity transition.

Company selection​

For tools that require a company:

  1. call list_companies;
  2. use the returned company identifier; and
  3. confirm the intended company before a write.

A connected account with several memberships is not automatically scoped to whichever company happens to be active in the Navaid browser.

Security model​

  • OAuth issues an access token for the authorised client.
  • The MCP service rejects ordinary Navaid web-session tokens that were not issued for an OAuth client.
  • Every request resolves permissions from current active memberships.
  • Removing or suspending a membership removes its company-derived authority.
  • The feature flag is enforced by the service.
  • External clients should never ask you to paste a Navaid verification code or browser token into a prompt.

Disconnect or revoke​

There is no current connector-management or OAuth-grant revocation screen in Navaid Settings.

To stop use:

  1. remove or disconnect Navaid in the external client;
  2. follow any grant-revocation process provided by the deployment's administrator; and
  3. report an unknown authorisation immediately.

Simply closing the external chat does not necessarily revoke its OAuth grant.

Test the connection​

Begin with read-only requests:

  1. “List my Navaid companies.”
  2. “Get the maturity summary for company.”
  3. “List pending tasks for company.”

Only after checking company resolution should you try a write. Confirm the result in Navaid's Company or Tasks page.

Troubleshooting​

The connector says MCP is disabled​

Ask a System Admin to enable the MCP connector. System Admin test access does not imply ordinary users can connect.

Restart connection from the external client's connector settings. Do not manually construct the authorization_id.

Use the same browser, preserve cookies required for authentication, and complete the passwordless code flow. The consent return path is carried through sign-in.

A tool says you are not a company member​

Call list_companies again. The membership may be inactive, or the external assistant may be using a company ID from another account.

A write is denied​

Check the tool's role requirement. Updating company facts needs Admin/Consultant authority; task actions require an active membership.

The client cannot discover OAuth​

Confirm the exact /functions/v1/mcp URL and remove any alternate project or frontend hostname. The client must support the protected-resource discovery flow.

Last updated on