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

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, while the underlying HTTP routes are implemented under 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 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 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, lockfiles, Docker Compose, or 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:

# 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:

# 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:

// 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:

# 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 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 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 and persisted in packages/db/src/schema/oauth.ts.
• Every AI action is audited via 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. 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}