Integrations
Connecting an outside assistant or service to SHIP. Which surface to use, what a token needs to carry, and why a follow-up instruction is not a restart.
Anything that can hold a token can drive SHIP. An assistant you talk to all day, or a build job of your own, files missions and follows them through the same API the console uses.
Pick a surface
Three ways in. The right one depends on where the thing runs, not on what it is.
| Surface | Use it when | Start here |
|---|---|---|
| MCP server | The assistant speaks MCP and talks to the platform directly, with no checkout of your repository in front of it | https://mcp.letsship.ai/mcp |
| CLI | A coding agent is already working inside your repository and can run shell commands | npx @lets-ship/cli |
| HTTP API | You are writing the integration yourself, or the client speaks neither of the above | https://api.letsship.ai/v1 |
They are the same capabilities underneath, because the MCP server and the CLI are both callers of that API, exactly as the console is. Nothing is reachable from one surface and locked away in another.
Give it a token, not your account
Mint an API token for the integration and grant it only the scopes that job needs. Bind it to one project with projectId as well, and every mission, run, environment, artifact and automation it can reach is confined to that project. That pairing is the narrowest useful grant for anything third-party.
The starting point for most assistants is the coding-agent set:
missions:run missions:read missions:write artifacts:readThat hands work over, follows it, sends follow-up instructions, and reads the proof a run produced. It deliberately leaves out agents:write, because the harness and model for a single mission travel in the dispatch itself, so changing your project's standing execution config stays a separate authority.
Authentication has the full scope list, the other recommended sets, and how to create a token from the console or over the API.
A token can never carry authority its minter lacks. If you mint one as a member and ask for an admin scope, the request is refused and names the scope it refused, rather than quietly issuing a weaker token.
What an integration does
It hands work over, then follows it, then answers the verdict when one comes back.
Handing over means starting a mission against an issue that already exists in your tracker, or creating the issue and the run together when there is no issue yet. Either way the mission can enter at the planner for a full run, at the builder with a plan you already wrote, or at the reviewer or QA stage with a pull request that is already open.
Following it means reading the mission for its stage, verdicts and cost, and reading the artifacts for what the run actually proved, such as the trace of a test session or a screenshot of the thing working.
Answering the verdict means sending the mission an instruction. That reaches the agents and puts the builder back on the open pull request with your feedback in hand.
None of this asks the integration to stay resident. A mission runs for tens of minutes and carries on regardless of whether the assistant that filed it is still in the conversation.
Do not restart a mission to send feedback. A restart re-evaluates the mission against its stored state, so an unchanged pull request with cached verdicts at the same commit correctly does nothing, and the caller is left reporting success for work that never happened. An instruction is the channel that changes what the agents were told.
Read the receipt
An instruction answers with a receipt: what was recorded, and what it will cause. An instruction sent against a merged pull request dispatches nothing, and says so in that reply.
Have the integration read the receipt before it reports back to a human. The failure mode worth designing against is an assistant that relays "sent your feedback to SHIP" on the strength of a 200, when the platform's own answer said the mission was already closed.
Where these two rules came from
Both of them came out of one integration. An external assistant, Instinct, was given a token and wired to a live mission on a customer repository, and it ran into each limit in turn.
Asked to send that mission some feedback, it had no channel for one, so it started the mission again. Twice. Both calls did exactly what a restart does: re-check the open pull request, find it unchanged with verdicts already cached at that commit, and correctly conclude there was nothing to do. Its own workaround was to post the feedback as an issue comment under the operator's GitHub account, because borrowing a human identity was the only way in that existed.
It then reported the instructions as delivered and corrected itself a moment later, because what it had was an acknowledgement that a request was queued rather than a receipt saying an instruction had been recorded.
Neither of those was the assistant getting it wrong. It did the best available thing with the surface it was given, and reported honestly enough that we could see the surface was the problem. The instruction channel and its receipt exist so the next integration starts from a better one.
Related
- MCP server for the hosted tool surface and a client configuration.
- Coding agents for agents that hand work over by running commands in your repository instead.
- Authentication for creating tokens and choosing scopes.
- API reference for the routes behind all of it.
How is this page?