Date: 2026-09-11 Date: 2026-09-10

​
Model Context Protocol

Use this lesson to build a practical, evidence-based Nova workflow for this topic.

​
What MCP adds

Model Context Protocol servers expose external tools and data sources to Nova through a standard interface. An MCP connection can let Nova work with systems such as source hosting, ticketing, knowledge stores, databases, messaging, or organisation-specific services without baking each integration into the core CLI. MCP does not bypass Nova’s safety model. A tool still has a defined input schema, runtime validation, approval policy, authentication requirements, and whatever access controls the remote service enforces.

​
Transport types

Nova supports three MCP transports:
  • HTTP — connect to a remote HTTP MCP endpoint.
  • SSE — connect using Server-Sent Events.
  • stdio — start a local process and exchange protocol messages over standard input and output.
Choose the transport required by the server. A stdio server is a local executable, so its command and environment deserve the same scrutiny as any other executable dependency.

​
Configuration scopes

Nova recognises three scopes when adding a server:
  • Local — available only for the current project, stored under that project path in ~/.compass/config.json; this is the default CLI scope.
  • Project — shared through .mcp.json at the project root.
  • User — available across projects and stored in ~/.compass/config.json.
Kore-CLI also loads portable user-scoped entries from ~/.compass/.mcp.json. Project loading prefers .mcp.json and can fall back to mcp.json. Never commit credentials in a project MCP file. Keep shared configuration limited to server names, transport details, and non-secret settings.

​
Add servers from the CLI

HTTP example with a placeholder endpoint:
stdio example:
The command syntax is:
HTTP and SSE entries can receive headers with --header; stdio entries can receive environment values with --env. Avoid placing secrets directly on a command line because shell history and process inspection may expose them. Nova also supports importing one server definition from JSON:

​
Inspect configuration

Use:
get masks recognised secret-like environment values and truncates authorisation headers in its display, but configuration files still need normal access protection.

​
Authentication

Check configured authentication state:
Start the supported OAuth flow for a server:
The command can also store an API token with --token, but supplying secrets directly on the command line has exposure risks. Prefer OAuth or secure environment/credential mechanisms supported by the server and operating system. OAuth availability depends on server metadata, provider restrictions, and client registration. A configured server may still fail if the remote account lacks permission.

​
Project-server approval

Project MCP configuration is code-adjacent and may be supplied by someone else. Nova tracks approval choices for project servers before trusting them. Reset those choices when configuration provenance changes:
You will be prompted to review project servers again.

​
Using MCP tools in conversation

Once configured, authenticated, and approved, MCP tools appear in Nova’s available tool surface. Some integrations are exposed lazily: Nova first activates the relevant capability, then calls the tool in a later step. A good request names the desired outcome, not an assumed raw tool name:
For externally visible actions, be explicit:
“Draft” and “send” are different authorisations.

​
Remove a server

Inspect the entry first, then remove it:
Removal changes configuration; it does not revoke credentials or remote tokens at the provider. Revoke those separately when decommissioning an integration.

​
Troubleshooting

  1. Run nova mcp list --verbose and confirm scope, transport, command, or endpoint.
  2. Run nova mcp auth-status for authentication problems.
  3. Verify the local executable exists for stdio servers.
  4. Check required environment variables without printing their values.
  5. Confirm organisation and remote-service policy permits the integration.
  6. Use nova doctor for wider Nova health checks.
  7. Reapprove project servers if .mcp.json changed unexpectedly.

​
What you learned

You can now apply the core practices in this lesson during a Nova session.

​
Try it yourself

Use this lesson’s guidance in a small, non-destructive task in a local project, then review the result before continuing.

​
Continue the course