Integrations
Connect an outside assistant or service to SHIP. Learn which surface to use, what a token must carry and why a follow-up instruction is not a restart.
Anything that can hold a token can use SHIP. An assistant that you talk to all day, or one of your own build jobs, can file missions and follow them. Both use the same API as the console.
Pick a surface
There are three ways in. The right one depends on where the integration 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 already works inside your repository and can run shell commands | npx @lets-ship/cli |
| HTTP API | You write the integration yourself, or the client speaks neither of the above | https://api.letsship.ai/v1 |
All three give the same capabilities, because the MCP server and the CLI both call that API, as the console does. No surface has a capability that the others do not have.
Give it a token, not your account
Create an API token for the integration, and give it only the scopes that the job needs. Also bind it to one project with projectId. Then every mission, run, environment, artifact and automation that it can reach is in that project only. Scopes and a project binding together give the narrowest useful grant for any third-party integration.
For most assistants, start with the coding-agent set:
missions:run missions:read missions:write artifacts:readWith that set, the integration can hand work over, follow it, send follow-up instructions and read the proof that a run produced. By design, the set does not include agents:write. The harness and model for a single mission go in the dispatch itself. A change to the execution config of your project needs a separate permission.
Authentication has the full scope list, the other recommended sets and the steps to create a token from the console or through the API.
A token can never have authority that its creator does not have. If you are a member and you ask for an admin scope, SHIP refuses the request and names the scope. It does not silently issue a weaker token.
What an integration does
An integration hands work over, follows it and then answers the verdict when one comes back.
To hand work over, start a mission against an issue that already exists in your tracker. If there is no issue yet, create the issue and the mission together. Either way, the mission can start at one of these stages:
- The Planner, for the full pipeline.
- The Builder, with a plan that you already wrote.
- The Reviewer or QA, with a pull request that is already open.
To follow the mission, read it for its stage, verdicts and cost. Then read the artifacts for what the mission proved, such as the trace of a test session or a screenshot that shows the change works.
To answer the verdict, send the mission an instruction. The instruction goes to the agents, and the Builder starts again on the open pull request with your feedback.
The integration does not have to stay connected. A mission runs for tens of minutes. It continues even if the assistant that filed it leaves the conversation.
Do not restart a mission to send feedback. A restart checks the mission again against its stored state. If the pull request did not change and has cached verdicts at the same commit, the restart correctly does nothing. The caller then reports success for work that did not happen. An instruction is the channel that changes what the agents work from.
Read the receipt
SHIP answers each instruction with a receipt. The receipt says what SHIP recorded and what the instruction will cause. An instruction for a merged pull request dispatches nothing, and the receipt says so.
Make the integration read the receipt before it reports back to a human. Design against one failure in particular. An assistant gets a 200 and tells the human "sent your feedback to SHIP". But SHIP's own answer said that the mission was already closed.
Where these two rules came from
Both rules came from one integration. An external assistant, Instinct, got a token and a connection to a live mission on a customer repository. The assistant then hit each limit, one after the other.
Someone asked it to send that mission some feedback. It had no channel for feedback, so it started the mission again, two times. Both calls did what a restart does. Each one checked the open pull request again, found it unchanged with verdicts already cached at that commit, and correctly found nothing to do. As its own workaround, the assistant posted the feedback as an issue comment under the operator's GitHub account. It used a human identity because no other way in existed.
Next, it reported the instructions as delivered and corrected itself a moment later. It had an acknowledgment that a request was in the queue, not a receipt that said SHIP recorded an instruction.
Neither problem was the fault of the assistant. It did the best thing that it could with the surface it had. Its reports were honest enough to show that the surface was the problem. The instruction channel and its receipt exist so that the next integration starts from a better surface.
Related
- MCP server for the hosted tool surface and a client configuration.
- Coding agents for agents that run commands in your repository to hand work over.
- Authentication for how to create tokens and choose scopes.
- API reference for the routes behind all of it.
How is this page?