# MCP server

> Ownkube runs a hosted remote MCP server. Connect any MCP client over OAuth and let your coding agent ship deployments, tail activity, and manage environments.

Ownkube runs a hosted **remote MCP server**. Point any MCP-capable client at one URL, sign in once, and your agent can create and roll back deployments, read logs and metrics, manage environments, projects and alerts, and deploy marketplace apps on your behalf. It uses the same permissions and tenant isolation as your dashboard account.

MCP (the [Model Context Protocol](https://modelcontextprotocol.io/)) is an open standard for connecting agents to tools. Because this is a remote server that speaks OAuth, any client with remote-MCP support connects the same way: Claude, other desktop and web assistants, agent frameworks, and your own code via an MCP SDK. The walkthrough below uses Claude as a concrete example; the URL and the flow are identical everywhere else.

## The server URL

```
https://app.ownkube.io/api/mcp
```

That is the only value you need. Authentication happens in the browser: there is no token or API key to copy, and nothing secret to paste into a config file.

## Connect your coding agent

Every client follows the same shape: point it at the server URL, authorize in the browser, pick an organization. The only thing that differs is where you add the server. Pick your client below for the exact step.

Clients that speak HTTP MCP (Claude Code, Cursor, GitHub Copilot, Windsurf) connect to the URL directly. Terminal and desktop clients that speak stdio (Codex, Zed, Claude Desktop) use `mcp-remote`, a small bridge that connects a local client to the remote endpoint and runs the browser sign in for you. It needs Node and `npx` on your machine.

#### Claude Code

1. **Install Claude Code**

```bash
npm install -g @anthropic-ai/claude-code
```

2. **Add the server**

```bash
claude mcp add --transport http ownkube https://app.ownkube.io/api/mcp
```

Streamable HTTP is what the `--transport http` flag targets. On first use Claude Code registers itself and starts the browser sign in automatically.

3. **Authenticate**

Run `/mcp` inside Claude Code and choose **ownkube**. A browser tab opens for you to sign in and pick an organization, then control returns to your terminal.

#### Cursor

1. **Open the MCP settings**

Download Cursor from cursor.com, then open **Settings > MCP**.

2. **Add the server**

Add it to `~/.cursor/mcp.json` (or a project-level `.cursor/mcp.json` to scope it to one repo):

```json title="~/.cursor/mcp.json"
{
 "mcpServers": {
   "ownkube": {
     "url": "https://app.ownkube.io/api/mcp"
   }
 }
}
```

3. **Authenticate**

Toggle the **ownkube** server on in **Settings > MCP**. Cursor opens a browser tab to sign in and pick an organization, then shows the server as connected.

#### GitHub Copilot

1. **Enable agent mode**

Install VS Code and the GitHub Copilot extension, then enable agent mode.

2. **Add the server**

Add it to the workspace config at `.vscode/mcp.json`:

```json title=".vscode/mcp.json"
{
 "servers": {
   "ownkube": {
     "type": "http",
     "url": "https://app.ownkube.io/api/mcp"
   }
 }
}
```

3. **Authenticate**

Open the MCP view and start the **ownkube** server. VS Code opens a browser tab for you to sign in and choose an organization, then marks the server running. Switch Copilot Chat to Agent mode to use the tools.

#### Windsurf

1. **Open the Cascade MCP settings**

Download Windsurf from codeium.com/windsurf, then open the Cascade MCP settings.

2. **Add the server**

```json title="~/.codeium/windsurf/mcp_config.json"
{
 "mcpServers": {
   "ownkube": {
     "serverUrl": "https://app.ownkube.io/api/mcp"
   }
 }
}
```

Windsurf uses `serverUrl` for a remote MCP server.

3. **Authenticate**

Press refresh in the MCP settings. Windsurf opens a browser tab to sign in and pick an organization, then shows **ownkube** as available.

#### Codex

1. **Install Codex**

```bash
npm install -g @openai/codex
```

2. **Add the server**

Codex speaks stdio MCP, so bridge it with `mcp-remote`:

```toml title="~/.codex/config.toml"
[mcp_servers.ownkube]
command = "npx"
args = ["-y", "mcp-remote", "https://app.ownkube.io/api/mcp"]
```

3. **Authenticate**

The first time Codex starts the **ownkube** server, `mcp-remote` opens a browser tab for you to sign in and choose an organization. After that it reuses the saved token.

#### Zed

1. **Open settings**

Download Zed from zed.dev, then open `settings.json`.

2. **Add the server**

Zed calls stdio MCP context servers, so bridge it with `mcp-remote`:

```json title="settings.json"
{
 "context_servers": {
   "ownkube": {
     "source": "custom",
     "command": "npx",
     "args": ["-y", "mcp-remote", "https://app.ownkube.io/api/mcp"]
   }
 }
}
```

3. **Authenticate**

Save the settings and open the agent panel. `mcp-remote` opens a browser tab for you to sign in and pick an organization, then Zed lists the **ownkube** tools.

#### Claude Desktop

1. **Install Claude Desktop**

Download Claude for macOS or Windows from claude.ai/download.

2. **Add the server**

Bridge it with `mcp-remote`:

```json title="claude_desktop_config.json"
{
 "mcpServers": {
   "ownkube": {
     "command": "npx",
     "args": ["-y", "mcp-remote", "https://app.ownkube.io/api/mcp"]
   }
 }
}
```

On paid plans you can also add Ownkube as a custom connector by URL from **Settings > Connectors**.

3. **Authenticate**

Restart Claude Desktop after saving. On first use `mcp-remote` opens a browser tab for you to sign in and pick an organization, then the **ownkube** tools appear in the chat.

Once connected, ask for what you need, for example *"list my Ownkube deployments"* or *"roll back the api deployment to the previous revision"*. Your agent picks the right tool and calls it.

The [`okctl` CLI](/docs/cli) covers the same ground from the terminal, scripts or a coding agent in your editor, and ships an agent skill. The MCP server and the CLI are two front doors onto the same Ownkube API.

## What your agent can do

Every tool is the same operation the dashboard and the CLI call, so an agent can do what you can do in your organization, with the same role limits.

### Read tools

| Area | Tools |
| --- | --- |
| Deployments | List and get deployments, live rollout status, revision history, recent log lines, build logs |
| Metrics | CPU, memory, requests, latency and network for an app; database and cache telemetry |
| Environments and projects | List and get environments, their shared variables, and projects |
| Datastores | Connection info for a database or cache (see the note below) |
| Alerts | Alert rules and recent firings |
| Billing | Wallet balance, spend controls, live burn rate, month-to-date and projected cost, daily history |
| Catalog | Marketplace apps, container registries, Compute regions and box sizes |
| Account | Your user profile and the organizations you belong to |

### Write tools

| Area | Tools |
| --- | --- |
| Deployments | Create, update, rename, restart, resync, delete; roll back to a revision; promote one deployment's config onto another; copy to another environment; move to another project; rebuild from source; upload local source and deploy it |
| Build settings | Auto-deploy on or off, build arguments, build root, builder size, maintenance mode |
| Public address | Check, suggest and change the `ownkube.app` label; add, verify and remove [custom domains](/docs/networking/custom-domains) |
| Environments and projects | Create, update and delete; replace an environment's shared variables |
| Jobs | Trigger a run now, cancel a run in flight |
| Datastores | Link a database or cache to an app (writes the connection string as a secret variable and redeploys) |
| Alerts | Create, update and delete alert rules |
| Marketplace | Check and deploy an app with its database and cache in one call; delete it as one unit. See [Marketplace](/docs/deployments/marketplace#deploy-from-a-coding-agent-or-the-cli) |
| Billing | Set spend controls, top up the wallet, start a plan checkout, open the billing portal, redeem a promo code (needs a card on file, added in the dashboard and never charged) |
| Own cloud | Connect, verify, reconnect and remove AWS accounts; create, cancel and destroy clusters. See [Clusters](/docs/own-cloud/clusters) and [Connect AWS](/docs/own-cloud/connect-aws) |

Write actions change real infrastructure. Tools that create, upgrade, roll back or destroy are described so the agent confirms with you before running them. Even so, treat an agent with this connector the way you would treat a teammate with dashboard access.

The connection-info tool returns a database's or cache's live host, username, password and connection string, and is marked so the agent only shares them with the person who asked. For wiring an app to a datastore the agent should prefer the link tool, which never returns the credential. Three operations stay in the [`okctl` CLI](/docs/cli) only: resetting a database password, opening a shell or tunnel, and point-in-time restore of a database.

## Security model

The connection is authorized with OAuth in your browser. There is no long-lived key to leak, and you can revoke the connector from your client at any time.

The agent sees exactly what your account can see, in the one organization you approved, with the same [role](/docs/organizations#roles). The tenant isolation that guards the dashboard guards every tool call too.

Ownkube never holds your AWS keys, and the agent cannot read them out. Cloud access is the role you granted during [AWS onboarding](/docs/own-cloud/connect-aws).

Every action runs through the same API as the dashboard and CLI, so it shows on the deployment's Activity tab like any other change.

## Multiple organizations

The connection is pinned to the organization you picked at approval time. To act on a different organization, add the connector a second time and choose the other organization when prompted, or remove and re-add it. Read-only questions about *which* organizations you belong to work regardless of the pinned one.

- [CLI (okctl)](/docs/cli)
- [Deploy from the marketplace](/docs/deployments/marketplace)
- [Security](/docs/security)

---

**Don't see a feature you need?** Email [support@ownkube.io](mailto:support@ownkube.io?subject=Feature%20request). Ownkube is shaped by the teams using it and we ship what our users ask for.

## Search

This site has a search endpoint: https://context7.com/api/v2/ask?siteKey=ask_c64dfe8ffaa8d3ad19576838&query=<URL-encoded question>. It returns documentation that answers the question, with a source link for each part. No API key is needed. If nothing matches, it says so.
