Connect your agent with MCP

Connect your coding agent to Northflank to deploy applications, manage databases, and inspect resources. Setup installs the Northflank skill or plugin and connects the hosted MCP server using your CLI login.

Requirements

Use the latest CLI and an installed copy of Claude Code, Codex, Cursor, or OpenCode. Codex also needs the codex command with plugin support.

Select a team when you log in. MCP uses that team's permissions. Personal and organization-scoped logins are not supported. You do not need to create another API token.

Connect with your CLI login

1. Install or update the CLI:

   pnpm add -g @northflank/cli@latest
   

2. If you need to log in, run nf login and select your team in the browser.

3. Set up your agent:

   nf agent setup --agent claude
   

4. Restart or reconnect the agent to load the new connection.

Replace claude with codex, cursor, or opencode. You can pass several names after --agent.

Setup applies to all your projects. It reads your saved CLI session when needed, without copying the token into agent configuration.

Ask your agent to set up Northflank

You can give your agent this prompt instead:

Set up the latest Northflank CLI, skill or plugin, and MCP connection for this agent.
Follow https://northflank.com/docs/v1/application/ai-agents/mcp-server.

Reuse my team login.
If login is needed, run nf login and wait for me to finish in the browser.
Never print saved credentials or ask me to paste a token.

Preview setup with nf agent setup --agent <agent> --dry-run.
Explain any replacement before applying it with --yes.
Preserve modified skills and other MCP servers.

Run nf agent status --check --agent <agent>.
Tell me if I need to reconnect.
Then use get_auth_context to confirm the team.
Do not create or change cloud resources.

Replace <agent> with claude, codex, cursor, or opencode. Keep the login command running while the user completes the browser step.

Confirm the connection

Run:

nf agent status --check --agent claude

Then ask your agent to show the authenticated team with get_auth_context. Make sure that it matches the team you intended.

Setup options

Option	Use
--yes	Apply without prompts. Specify --agent. Browser login can still require your input.
--dry-run	Preview changes without installing or testing authentication.
--no-mcp	Install skills or plugins only. Add --scope user or --scope project for non-interactive use. Codex plugins require user scope.

Setup preserves modified skills and other MCP servers. Use nf agent update --agent claude to update, or nf agent remove --agent claude to remove managed installation files and MCP configuration.

Login changes and expiry

If your session expires, MCP returns login instructions to the agent. Follow those instructions to renew the same context and team. This updates your normal CLI login too, and the running bridge uses it on the next request.

The --override login option clears that context's saved resource defaults. Reconnect only if the agent disconnected. To change teams, select the new CLI context, rerun setup, and reconnect.

Troubleshooting

Problem	Next step
No tools appear	Run nf agent status --check --agent claude, then reconnect. In Claude Code, use /mcp and claude mcp get northflank to inspect the active connection.
Login is rejected	Use a team login. For an expired session, follow the returned login instructions.
An environment token overrides your login	Unset NF_API_TOKEN, NORTHFLANK_API_TOKEN, NF_API_HOST, and NORTHFLANK_API_HOST before setup.
Access is denied	Make sure that the credential's role permits the requested operation.
CLI or Node.js moved	Rerun setup with the installed CLI, then reconnect.

Deploy your first application

Deployment creates billable resources. Ask your agent:

Deploy nginx:latest in a new Northflank project named mcp-demo. Expose HTTP port 80. Show me the region and plan before creating resources, then return the working URL.

For Git deployments, push your changes first. Private repositories need a Git connection with access to the repository. Follow any authorization link the agent returns.

Your agent can also manage jobs, databases, and existing resources. Ask it to inspect the available tools for your task. If creation fails partway through, inspect any returned resource IDs before retrying.

The Northflank skill supplies platform guidance. MCP supplies authenticated tools. CLI setup installs both by default.

Use an API token for authentication

For clients without the CLI, connect directly with a team API token.

Prepare your token

Use a client that supports Streamable HTTP and an Authorization header. The endpoint is https://mcp.northflank.com/mcp. Northflank MCP does not support OAuth login.

1. Create a team API token with permissions for the resources you want the agent to manage.
2. Store it as NORTHFLANK_API_TOKEN in the environment of the agent process, using your shell or secret manager.
3. Start the agent with that environment available.

Set the variable to the token alone, without the Bearer prefix. The client configuration adds that prefix.

For deployment, the role needs permission to create and read the relevant resources. A new project also needs project creation permission. Connecting a Git account needs a user-associated token with Git management permission. Public repositories do not require a Git account connection.

Do not paste the token into chat or commit it to Git. Start the agent with the environment variable available. An already running desktop app does not inherit variables from another terminal.

Add MCP to your client

Merge the Northflank entry into your existing configuration. Preserve other servers. After saving, restart or reconnect the client so it loads the new configuration and environment.

Codex

Add this table to ~/.codex/config.toml:

[mcp_servers.northflank]
url = "https://mcp.northflank.com/mcp"
bearer_token_env_var = "NORTHFLANK_API_TOKEN"

This configuration sends the variable as a bearer token. MCP OAuth login is not required. See the Codex MCP documentation for configuration locations and connection controls.

Claude Code

Add this entry to .mcp.json in your project:

{
  "mcpServers": {
    "northflank": {
      "type": "http",
      "url": "https://mcp.northflank.com/mcp",
      "headers": {
        "Authorization": "Bearer ${NORTHFLANK_API_TOKEN}"
      }
    }
  }
}

Approve the project MCP configuration when prompted. Use /mcp to inspect the connection. See the Claude Code MCP documentation.

Cursor

Add this entry to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one project:

{
  "mcpServers": {
    "northflank": {
      "url": "https://mcp.northflank.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NORTHFLANK_API_TOKEN}"
      }
    }
  }
}

Cursor uses ${env:NAME} for environment variables. See the Cursor MCP documentation for connection controls.

OpenCode

Add this entry to your project's opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "northflank": {
      "type": "remote",
      "url": "https://mcp.northflank.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:NORTHFLANK_API_TOKEN}"
      }
    }
  }
}

Keep oauth set to false for this API-token connection. See the OpenCode MCP documentation.

Other clients

Use Streamable HTTP with the endpoint above and this request header:

Authorization: Bearer <YOUR_TEAM_API_TOKEN>

Use the client's secret storage or environment substitution where available. Configuration syntax differs between clients.