# Openship MCP Endpoint AI Agent API Tools: Architecture and Integration Guide

> Explore Openship MCP endpoint AI agent API tools for seamless integration. Authenticate with OAuth 2.1 and manage deployments, logs, and domains with the same permissions as the web UI.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: architecture
- Published: 2026-08-19

---

**Openship exposes a standards-compliant MCP endpoint at `POST /api/mcp` that lets AI agents authenticate via OAuth 2.1 and invoke deployment, logging, and domain-management tools under the exact same permission layer as the web UI.**

Openship is an open-source, self-hostable deployment platform that unites a **control plane**, an **edge server**, and an **MCP (Model Context Protocol) endpoint** to let developers, CI pipelines, and AI agents deploy and manage applications. The `oblien/openship` repository implements this architecture with a unified permission model and audit-first design. Understanding the Openship MCP endpoint AI agent API tools is essential for safely integrating Claude, Cursor, VS Code Copilot, and other agents into your deployment workflow.

## What Is the Openship MCP Endpoint?

The **MCP endpoint** is a standards-compliant OAuth 2.1 server that exposes a `POST /api/mcp` route. According to the `oblien/openship` source code, AI agents such as Claude, Cursor, and VS Code Copilot call this route to run tools, read logs, manage domains, and more. User-facing documentation for the protocol, OAuth flow, and client management lives in `apps/web/content/docs/mcp.mdx`.

All MCP calls are re-checked against the user’s existing permissions, and credential-type routes—such as personal access tokens—are never exposed as tools.

## Core Architecture: Control Plane, Edge, and MCP

Openship’s architecture consists of three integrated components.

### Control Plane

The **control plane** is the core service that orchestrates builds, stores metadata, and drives deployments. It can run as a **desktop app**, a **self-hosted server** launched with `openship up`, or on **Openship Cloud**, as documented in the README.

### Edge Server

The **edge server** is an OpenResty (NGINX + Lua) container that terminates TLS, routes traffic, and handles automatic Let’s Encrypt certificates. It writes a reverse-proxy vhost after the application is running, so any DNS or certificate issue surfaces as an “action required” state rather than a hard failure.

### MCP Server and API Routes

The MCP server reuses the platform’s existing API layer. MCP-exposed tools are regular backend functions—such as `deploy`, `logs`, and `domains`—that are automatically surfaced to authorized agents. The front-end client used by the web dashboard to invoke these tools lives in [`apps/dashboard/src/lib/api/mcp.ts`](https://github.com/oblien/openship/blob/main/apps/dashboard/src/lib/api/mcp.ts), while the underlying HTTP routes are implemented under [`apps/api/src/routes/mcp.ts`](https://github.com/oblien/openship/blob/main/apps/api/src/routes/mcp.ts).

## How AI Agents Authenticate via OAuth 2.1

Before invoking tools, an AI agent must complete an OAuth 2.1 flow. The repository includes a helper script at [`scripts/mcp-oauth-check.ts`](https://github.com/oblien/openship/blob/main/scripts/mcp-oauth-check.ts) that validates the end-to-end exchange—including redirects and token issuance—against a running instance.

Once the user authorizes the client, the agent receives a bearer token. Database bindings for these clients are stored in [`packages/db/src/schema/oauth.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/oauth.ts) inside the `oauth` and `personal-access-token` tables. This schema tracks which user authorized each AI agent, enabling fine-grained revocation later.

## MCP Tools and the Unified Permission Model

MCP tool calls run through the same permission-checking layer as a normal browser session. As implemented in `oblien/openship`, this means an AI agent can only act **within the organization** and **only on resources the user allowed** during authorization.

Adding a new capability simply requires registering a route in the API layer; the MCP server automatically exposes it to authorized agents. This extensible design keeps the surface area consistent across human and AI interactions.

## The Deployment Lifecycle with MCP Interaction

The full lifecycle from source code to AI-driven management follows five stages:

1. **Detect** – Openship inspects the repository ([`package.json`](https://github.com/oblien/openship/blob/main/package.json), lockfiles, Docker Compose, or [`openship.json`](https://github.com/oblien/openship/blob/main/openship.json)) to infer the build stack and start command.

2. **Build** – The control plane builds a Docker image or bare process on the target host. The resulting artifact is stored as a snapshot for reproducible rollbacks.

3. **Run** – The artifact launches either inside a Docker container (Compose mode) or as a supervised host process (bare mode).

4. **Route and Secure** – The edge server provisions a reverse-proxy vhost and automatically obtains a Let’s Encrypt certificate.

5. **MCP Interaction** – An AI agent requests an OAuth 2.1 token from `/api/mcp`. After user authorization, the agent invokes MCP-exposed tools. Each tool call is audited and scoped to the permissions granted at authorization time.

## Code Examples: Authenticating and Calling MCP Tools

Below are runnable snippets for interacting with the Openship MCP endpoint.

First, obtain an OAuth 2.1 token for the MCP client:

```bash

# Obtain an OAuth 2.1 token (replace <INSTANCE_URL>, <CLIENT_ID>, <CLIENT_SECRET>)

curl -X POST "<INSTANCE_URL>/api/mcp/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>"

# → returns { "access_token": "ops_h2c_…", "token_type": "Bearer", "expires_in": 3600 }

```

Next, call an MCP-exposed tool to deploy a project:

```bash

# Deploy the current project via an MCP tool

curl -X POST "<INSTANCE_URL>/api/mcp/tools/deploy" \
  -H "Authorization: Bearer ops_h2c_…" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"my‑app"}'

# → JSON response with build status, logs URL, and deployed domain

```

You can also use the Node SDK, which is the same library the CLI consumes:

```typescript
// Using the Node SDK
import { OpenShipMCP } from "openship-sdk";

const mcp = new OpenShipMCP({
  baseUrl: process.env.OPENSHIP_URL,
  token: process.env.OPENSHIP_MCP_TOKEN,
});

await mcp.deploy({ projectId: "my-app" });
console.log("✅ Deploy triggered, check the dashboard for progress");

```

To revoke a client and disconnect an AI agent, call the revoke endpoint:

```bash

# Revoke a client and invalidate its tokens

curl -X POST "<INSTANCE_URL>/api/mcp/oauth/revoke" \
  -H "Authorization: Bearer ops_h2c_…" \
  -d '{"clientId":"<CLIENT_ID>"}'

# Tokens are instantly invalidated; subsequent calls fail with 401

```

## Audit-First Design and Security Tracking

Every MCP tool call is logged with a distinct action label. The audit taxonomy defined in [`packages/core/src/audit-taxonomy.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/audit-taxonomy.ts) assigns sources such as `oauth:<clientId>` to AI-driven operations, giving operators full traceability.

Revoking a client in **Settings → MCP** instantly invalidates its tokens. Because the `oauth` and `personal-access-token` tables in [`packages/db/src/schema/oauth.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/oauth.ts) track each grant, operators can audit and remove access without affecting other sessions.

## Summary

- The Openship MCP endpoint at `POST /api/mcp` provides a standards-based OAuth 2.1 gateway for AI agents.
- MCP tools such as `deploy`, `logs`, and `domains` reuse the same backend functions and permission checks as the web UI.
- Authentication is validated by [`scripts/mcp-oauth-check.ts`](https://github.com/oblien/openship/blob/main/scripts/mcp-oauth-check.ts) and persisted in [`packages/db/src/schema/oauth.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/oauth.ts).
- Every AI action is audited via [`packages/core/src/audit-taxonomy.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/audit-taxonomy.ts) with a traceable `oauth:<clientId>` source.
- Operators can revoke agent access instantly through the dashboard or the revoke API.

## Frequently Asked Questions

### What is the exact URL for the Openship MCP endpoint?

The MCP endpoint is available at `POST /api/mcp` on your Openship instance. AI agents request tokens from `/api/mcp/oauth/token` and invoke tools at paths such as `/api/mcp/tools/deploy`.

### How does Openship prevent AI agents from accessing sensitive credentials?

Credential-type routes, including personal access tokens, are never registered as MCP tools. The platform enforces a unified permission model, so every tool call is re-checked against the user’s ACLs at runtime.

### Where is MCP client authorization data stored?

Client registrations and user grants are stored in the `oauth` and `personal-access-token` tables defined in [`packages/db/src/schema/oauth.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/oauth.ts). This schema enables fine-grained tracking and revocation of individual AI agent clients.

### How can I audit actions performed by an AI agent?

Every MCP tool call creates an audit row with a source label like `oauth:<clientId>`, as defined in [`packages/core/src/audit-taxonomy.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/audit-taxonomy.ts). You can review these logs in the Openship dashboard or query the audit table directly for a complete history of AI-driven deployments and configuration changes.