Connect your agent with MCP

Connect your coding agent to Northflank with Model Context Protocol (MCP), a standard for calling tools from an AI client. The hosted server lets agents deploy applications and jobs, manage databases, and inspect resources.

Northflank hosts the server. You do not need the Northflank CLI, a local MCP process, or a deployment in your team.

Requirements

Use a team API token and a client that supports Streamable HTTP with an Authorization header. The token's role controls which resources and operations the agent can access.

The hosted endpoint is:

https://mcp.northflank.com/mcp

The server accepts team API tokens and team workload identity tokens. Personal, organization, and browser session tokens are not accepted by this hosted entry point.

MCP authentication currently uses a bearer token, not an OAuth sign-in flow. Clients that require OAuth and cannot send a custom Authorization header cannot use this setup.

Prepare your token

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.

The configurations below reference the environment variable instead of storing the token in a project file. Do not paste the token into chat or commit it to Git. A desktop app must receive the variable in its own process environment. Setting it in an unrelated terminal does not update an already running app.

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.

Confirm the connection

Ask the agent:

Use the Northflank MCP to show my authenticated team and access scope. Do not create or change resources.

The agent can use get_auth_context to read the credential context. Make sure that the returned team matches your intended team.

If no Northflank tools appear, make sure that the server is enabled and reconnect the client. The endpoint is a protocol URL, not a web page. Opening it in a browser is not a connection test.

Deploy your first application

Deployment creates billable resources. Use a new project name, and choose a region and plan that fit your requirements.

Ask the agent:

Use the Northflank MCP to deploy nginx:latest into a new project named mcp-demo. Expose HTTP port 80. Show the region and plan before creating resources, then return the public URL when the app is ready.

The agent uses deploy_app and follows the returned status instructions. Creation does not establish readiness. For a web application, the agent must also check the public URL before reporting success.

For a Git repository, ask:

Use the Northflank MCP to deploy this repository's remote branch into a new project named repo-demo. Use its Dockerfile. If Northflank needs Git access, give me the authorization link and resume after I authorize it.

Git deployment uses the remote repository. Uncommitted or unpushed local changes are not included. The agent can inspect local build configuration, but the hosted MCP does not read your local files.

Public repositories work without linking a Git account. For private repositories, the team needs a connection with access to that repository.

If Git access is missing, the deployment workflow can return a browser authorization link before creating resources. Complete the link, then ask the agent to continue. It resumes with the original inputs and the returned session ID.

If you connect the repository separately in Northflank, the original session can remain pending. Tell the agent that you connected it separately. Retry the original deployment without gitConnectionSessionId so the workflow checks repository access again. Preserve an explicitly selected source.vcsLinkId unless you intend to select a different connection. Do not create another authorization session while the original one is pending.

Git authorization grants repository access. It does not replace the team API token used to authenticate the MCP connection.

Available workflows

The MCP includes deployment workflows and detailed resource operations. Permissions apply to every operation.

Common operations appear directly in the tool list. The agent finds advanced operations with search_tools and calls them through execute_tool. It uses get_tool_schema only for omitted fields or constraints. Returned next.tool names can be executed without another search.

Task	Tools and behavior
Deploy an image or Git application	deploy_app checks Git access when needed and creates a service in an existing or new project.
Create a manual or scheduled job	deploy_job supports image and Git sources. Manual execution uses run_job.
Add a database	create_database handles common database settings and explicit environment-variable linking.
Inspect deployment progress	get_deployment_status summarizes build, rollout, run state and active source revisions. Follow its next action for recovery or diagnostics. A source revision match does not confirm the exact build artifact.
Manage existing resources	Resource operations cover projects, services, jobs, addons, secrets, volumes, harnesses, and supported BYOC operations.
Investigate a failure	diagnose gathers service, job or addon health, infrastructure events, deployment revisions, logs and metrics. For BYOC, it also reads cluster and node-pool configuration.

Diagnosis gathers evidence without changing resources. Missing permissions produce partial results. It does not prove a root cause or test application connectivity. Use get_deployment_status or get_addon for routine polling.

list_addon_types returns Northflank-managed addon types and custom addon types available to your team. Managed type details include versions, storage sizes and replica options. Storage classes depend on the target cluster and are not included in type discovery.

For BYOC databases, set create_database.storageClass to a class supported by the target cluster. Its default is nvme, which is unavailable on some clusters. Addon type discovery does not confirm that a storage class exists on your cluster.

list_cluster_nodes returns recorded BYOC nodes and their RUNNING or DELETED state. This state does not establish Kubernetes readiness or schedulability.

The MCP does not expose every public API operation. Ask the agent to inspect the available tools before assuming a capability exists.

Use MCP with the Northflank skill

The Northflank skill provides deployment guidance and platform knowledge. MCP supplies authenticated tools that execute operations.

You can use either independently. Install the skill alongside MCP when you want both guidance and tools. Installing the skill does not configure the MCP connection or grant account access.

Workload identity

Agents running on Northflank can use a team workload identity token instead of a copied team API token. The token's permissions and project restrictions still apply.

Send the workload token in the same Authorization header. If NORTHFLANK_API_TOKEN_FILE is provided, use a client that can read the mounted token file again when the token rotates.

The static environment configurations above do not provide automatic workload token refresh. Use a client credential mechanism that reads the mounted token file before each request or refreshes it when authentication fails.

Workload identities cannot authorize a personal Git account. A team member must grant the required repository access in the team's Git integrations.

Prepare a workload token helper

Codex and Claude Code can generate authentication headers with a local helper. The examples below require Node.js and access to the mounted workload token file.

Save this helper as northflank-mcp-headers.cjs in a trusted directory. The client runs it. Do not run it in a shared terminal because its output contains the token.

const { readFileSync } = require('node:fs');
const tokenFile = process.argv[2];
if (!tokenFile) throw new Error('Supply the workload token file path.');
const token = readFileSync(tokenFile, 'utf8').trim();
if (!token) throw new Error('The workload token file is empty.');
process.stdout.write(JSON.stringify({ Authorization: `Bearer ${token}` }));

Refresh workload tokens in Codex

For a local Codex HTTP connection, configure http_headers_helper in ~/.codex/config.toml. Use the helper above and replace both file paths. Use the MCP URL for the workload's Northflank environment.

[mcp_servers.northflank]
url = "https://mcp.northflank.com/mcp"
http_headers_helper = "node /absolute/path/northflank-mcp-headers.cjs /absolute/path/to/workload-token"

Remove bearer_token_env_var and other static Authorization headers for this server. An explicit bearer token or stored OAuth credential takes precedence over the helper's Authorization header.

Codex caches the helper's headers for the connection. After a same-origin POST returns HTTP 401 or 403, it refreshes the headers once. It retries only if the helper returns changed values. The helper is not supported for connections through a remote execution environment. Do not retry uncertain mutations yourself.

Refresh workload tokens in Claude Code

Claude Code supports dynamic authentication headers.

1. Save the helper from Prepare a workload token helper.

2. Add an HTTP MCP configuration with headersHelper. Replace both file paths. Use the MCP URL for the workload's Northflank environment. Remove any static Authorization header for this server.

{
  "mcpServers": {
    "northflank": {
      "type": "http",
      "url": "https://mcp.northflank.com/mcp",
      "headersHelper": "node /absolute/path/northflank-mcp-headers.cjs /absolute/path/to/workload-token"
    }
  }
}

3. Reconnect through /mcp. For project configuration, trust the directory before the helper can run.

Claude Code reads fresh headers on connection and reconnect. After a tool call receives HTTP 401 or 403, it refreshes the headers and retries once. It does not read the file before every request. A permission denial still requires a role or scope change. Do not retry uncertain mutations yourself.

Troubleshooting

Symptom	Action
Missing tools or a connection failure	Make sure that the client enables the server, uses Streamable HTTP, and sends requests to the URL ending in /mcp.
401 authentication error	Make sure that the agent receives the token variable and sends a valid team token. Replace an expired or revoked token.
403 permission error	Inspect the token role and workload restrictions. Grant the required permission or use a credential with the intended scope.
An unexpected OAuth prompt	Configure the bearer header. In OpenCode, set oauth to false. The hosted server does not provide MCP OAuth login.
Git authorization cannot complete	Follow the returned recovery instructions. Check the credential's team and user context before requesting a replacement link.

If a request fails after resource creation, retain the returned resource IDs. Inspect those resources before retrying so you do not create duplicates.