MCP for AI Agents

Cybership MCP gives AI agents controlled access to your ShipOS public API. Claude Desktop can 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.

Connect Claude Desktop

Claude Desktop does not need a Cybership API key. In Claude's custom connector settings:

1. Add a custom connector with the URL https://api.cybership.io/mcp.
2. Choose Connect or Authenticate when Claude opens the Cybership sign-in flow.
3. Sign in to Cybership if prompted.
4. Explicitly select the Cybership team Claude should access. The active team from another browser tab is not selected automatically.
5. Choose Read only, Read and operate, Full operational access, or Custom permissions and review the operations shown.
6. Give the connection a recognizable name and approve it.
7. Return to Claude and confirm that the Cybership tools are available.

Claude 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. Choose Disconnect there, or disconnect it in Claude, to revoke its tokens without affecting your account or any static API keys.

Connect ChatGPT web

Use ChatGPT in your browser at chatgpt.com for custom MCP apps:

1. Open Settings → Apps and enable developer mode if your workspace requires it.
2. Create a custom app with https://api.cybership.io/mcp as its MCP endpoint.
3. Choose Scan Tools, complete Cybership sign-in, and explicitly select the team and permissions to grant.
4. Return to ChatGPT web and wait for the tool scan to finish before creating or using the app.

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.

Recommended Agent Workflow

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 Desktop or ChatGPT web, disconnect and reconnect the custom connector. 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 scanned or used the Cybership tools, the message refers to ChatGPT's connector binding—not a Cybership API resource or operation key. Full custom MCP write support is currently beta in ChatGPT.

1. Use ChatGPT web, confirm the Cybership app is still enabled, and start a new chat with the app selected.
2. If you manage a published workspace app, refresh its actions and confirm execute_cybership_operation is enabled. For a draft app, rescan its tools or recreate the app if the binding remains unavailable.
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 app 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.