MCP for AI Agents

Connect Claude, ChatGPT, Codex, and other MCP clients to Cybership

Cybership MCP gives AI agents controlled access to your ShipOS public API. Claude and ChatGPT connect with Cybership sign-in and OAuth. CLI clients can continue to use a dedicated static API key.

Requirements

Before connecting an MCP client, decide which team it should access and which operational permissions it needs. You need the Write MCP permission on that team to authorize a connection. The connector can receive only operational permissions you currently hold, and it can never receive the MCP-management permission itself.

An MCP client can read or change Cybership data within its granted permissions. Start with Read only and grant write or delete permissions only when the workflow requires them.

Approve the Cybership sign-in

Claude, ChatGPT, and Codex all open the same Cybership sign-in page when you connect. None of them needs a Cybership API key. On that page:

  1. Sign in to Cybership if prompted.
  2. Explicitly select the Cybership team the AI should access. The active team from another browser tab is not selected automatically.
  3. Choose Read only, Read and operate, Full operational access, or Custom permissions and review the operations shown.
  4. Give the connection a recognizable name and approve it.

The AI receives short-lived OAuth tokens, not your Cybership API key or browser session. The connection is listed under Team Settings → MCP Connections, including its registered client, permissions, status, and recent use. To revoke access, choose Disconnect there. The AI loses access to Cybership on its next request, and your account and any static API keys keep working. Removing the connector in Claude or ChatGPT only removes it from that app and does not always end its access to Cybership, so also choose Disconnect in Cybership.

Connect Claude

Custom connectors work in Claude on the web at claude.ai, in Claude Desktop, and in Cowork. Anthropic offers them on the Free, Pro, Max, Ultra, Team, and Enterprise plans. The Free plan allows one custom connector. A connector you add in one Claude app is available in the others.

Free, Pro, Max, or Ultra plan

  1. In Claude, go to Customize → Connectors.
  2. Select Add, then Add custom connector.
  3. Enter Cybership as the name and https://api.cybership.io/mcp as the remote MCP server URL, then click Continue.
  4. Keep the authentication settings Claude marks Detected. Cybership supports the recommended Use Claude's published identity OAuth client, so you do not need a client ID or secret.
  5. Click Add, then click Connect and approve the Cybership sign-in.

Team or Enterprise plan

Only an Owner (or, on Enterprise, a member whose custom role can manage the organization's libraries) can add a custom connector. The Owner adds it once for the organization:

  1. Go to Organization settings → Connectors.
  2. Select Add, then Custom. If Claude asks for the connector type, choose Web.
  3. Enter Cybership as the name and https://api.cybership.io/mcp as the remote MCP server URL, then click Continue.
  4. Keep the authentication settings Claude marks Detected, then click Add.

Each member then connects with their own Cybership account:

  1. Go to Customize → Connectors.
  2. Find Cybership, which has the Custom label.
  3. Click Connect and approve the Cybership sign-in.

To turn Cybership on or off for one conversation, select + in the chat, choose Connectors, and use the Cybership toggle.

Connect ChatGPT

ChatGPT now calls connected tools Plugins (earlier versions called them Connectors, then Apps). You no longer need to turn on developer mode. Set up the plugin in ChatGPT on the web at chatgpt.com.

Who can add it depends on your ChatGPT plan:

PlanCustom MCP server access
BusinessWorkspace admins and owners can add Cybership with read and write actions. Other members can use it after an admin or owner publishes it to the workspace.
Enterprise or EduAdmins and owners can add Cybership, and so can members whose role has the Create plugins with MCPs permission. Only admins and owners can publish it to the workspace.
ProYou can add Cybership for read actions only. OpenAI limits write actions from custom MCP servers to Business, Enterprise, and Edu.

OpenAI's guide does not offer custom MCP servers on other ChatGPT plans.

To add Cybership:

  1. In ChatGPT, open Plugins from the sidebar, or go to chatgpt.com/plugins.
  2. Select the + button, then Add custom MCP server.
  3. Enter Cybership as the name. Under Connection, enter https://api.cybership.io/mcp as the server URL.
  4. For authentication, choose OAuth. Leave any client ID and secret empty; ChatGPT registers itself with Cybership automatically. If ChatGPT asks how to register the client, either Client ID Metadata Document (CIMD) or Dynamic Client Registration (DCR) works.
  5. Review the risk warning and select I understand and want to continue.
  6. Select Create as a plugin. When ChatGPT opens the Cybership sign-in page, approve the Cybership sign-in.
  7. Review the Cybership tools ChatGPT discovered, then install the plugin.
  8. Start a new chat, type @, and select Cybership.

ChatGPT asks you to confirm write actions before it runs them. To pull in tool changes later, open Cybership in Plugins and select Refresh.

Add and test the plugin at chatgpt.com, as OpenAI's setup guide describes. The ChatGPT and Codex desktop apps may show a completed browser sign-in without finishing the connection.

Connect Codex with OAuth

For Codex CLI, register the URL and start OAuth login:

codex mcp add cybership --url https://api.cybership.io/mcp
codex mcp login cybership

Complete Cybership sign-in, explicit team selection, and permission review in the browser.

Connect an API-key or CLI client

For Codex, Claude Code, and other clients that support custom bearer credentials:

  1. Create a Cybership API key.
  2. Give the key only the permissions the agent needs.
  3. Store the complete key in a secure environment variable. Do not commit it to source control or paste it into shared configuration.

MCP Endpoint

Connect your MCP client to:

https://api.cybership.io/mcp

Cybership MCP uses Streamable HTTP. API-key clients authenticate by sending the key as a Bearer token:

Authorization: Bearer cyb_<secret>_<checksum>

Codex setup

Store the key in an environment variable, then register the remote MCP server:

export CYBERSHIP_API_KEY='cyb_<secret>_<checksum>'

codex mcp add cybership \
  --url https://api.cybership.io/mcp \
  --bearer-token-env-var CYBERSHIP_API_KEY

For project-scoped Codex configuration, add the following to .codex/config.toml in a trusted project:

[mcp_servers.cybership]
url = "https://api.cybership.io/mcp"
bearer_token_env_var = "CYBERSHIP_API_KEY"
default_tools_approval_mode = "writes"

Restart Codex after changing MCP configuration. Run codex mcp list or use /mcp in the Codex terminal interface to confirm the connection.

Other API-key clients

For any client that supports remote Streamable HTTP servers, configure:

  • Server URL: https://api.cybership.io/mcp
  • Authentication: Bearer token
  • Bearer token: Your complete Cybership API key

The exact field names vary by client. Prefer environment-variable or secret-manager support instead of storing the API key directly in client configuration. If the client supports standard MCP OAuth but not custom headers, use its URL-and-login flow instead.

Available Tools

search_cybership_operations

Search the public API catalog by capability, resource, operation ID, path, or tag. Results include stable operation keys such as GET /shipos/products/{product_id}.

describe_cybership_operation

Inspect the documented path parameters, query parameters, request body, responses, and referenced schemas for an operation.

execute_cybership_operation

Execute an operation using its exact operation key and documented inputs. The connected OAuth grant or API key determines which team and resources the request can access.

  1. Search for an operation that matches the task.
  2. Describe the selected operation before supplying parameters or a request body.
  3. Execute read operations directly.
  4. Review the intended change before executing a write operation.
  5. Set confirm_write: true only after the change is confirmed.

All POST, PUT, PATCH, and DELETE operations require explicit write confirmation.

Rate Limits and Large Responses

OAuth MCP connections have their own public API rate-limit tier, defaulting to Tier 1 (30 operations per minute), and can be assigned the same higher tiers as API keys. Static-key MCP clients use their API key's tier. OAuth-grant and API-key counters are independent. MCP responses are limited to 1 MiB, so use documented pagination and filtering parameters for large collections.

Troubleshooting

Unauthorized

  • For Claude or ChatGPT, disconnect and reconnect Cybership in Customize → Connectors (Claude) or Plugins (ChatGPT). Confirm the connection remains active under Team Settings → MCP Connections.
  • If a desktop OpenAI client says authorization completed but still shows Authorize, repeat setup at chatgpt.com.
  • For API-key clients, confirm the complete API key is present in the configured environment variable and remains active and unexpired.
  • Restart the MCP client after changing its environment or configuration.
  • Ensure the key belongs to the expected Cybership account.

Operation Not Found

  • Run search_cybership_operations instead of guessing an operation key.
  • Confirm the operation is available in the Cybership public API and that the connected key has the required permissions.
  • Run describe_cybership_operation to inspect the operation's current inputs.

Write Confirmation Required

Review the proposed change, then retry the operation with confirm_write: true. Do not enable write confirmation globally for unattended agents.

ChatGPT Reports an Executor Resource Is Missing

If ChatGPT reports Resource not found: Cybership.execute_cybership_operation after it successfully discovered or used the Cybership tools, the message refers to ChatGPT's link to the Cybership plugin. It is not a Cybership API resource or operation key.

  1. Use ChatGPT at chatgpt.com, confirm the Cybership plugin is still installed, and start a new chat with @Cybership selected.
  2. Open Cybership in Plugins, select Refresh, and confirm execute_cybership_operation is turned on. If your workspace admin published Cybership for the workspace, ask them to refresh its tool list in workspace settings. If the tool is still missing, remove the plugin and add it again.
  3. Retry a harmless read operation first.
  4. Before retrying any failed write, check Cybership for the intended result so a successful but unacknowledged request is not duplicated.

If the error persists, reconnect the plugin and report the conversation URL and failure time to OpenAI support. Include whether Team Settings → MCP Connections shows recent use; that helps distinguish a request that reached Cybership from a ChatGPT-side invocation failure.

Authentication

The ShipOS API uses API keys to authenticate requests. This guide explains how to create API keys and use them to authenticate your API requests.

Rate Limits

Understand ShipOS API rate limits, available tiers, and reliable handling of throttled responses.

On this page

RequirementsApprove the Cybership sign-inConnect ClaudeFree, Pro, Max, or Ultra planTeam or Enterprise planConnect ChatGPTConnect Codex with OAuthConnect an API-key or CLI clientMCP EndpointCodex setupOther API-key clientsAvailable Toolssearch_cybership_operationsdescribe_cybership_operationexecute_cybership_operationRecommended Agent WorkflowRate Limits and Large ResponsesTroubleshootingUnauthorizedOperation Not FoundWrite Confirmation RequiredChatGPT Reports an Executor Resource Is Missing