Resources and tools
The Seamward MCP server exposes thirteen tools, six resources, and two prompts. Twelve tools and every resource only read. One tool, submit_repair_candidate, records a fix your team made as a proposal awaiting approval; it needs a scope that is never granted by default. Nothing a client calls can approve, merge, deliver or deploy a repair, or change your integrations or your production systems.
Current registered contract
These are the names registered by the current server. Every tool is scoped to
a previously reviewed workspace, mode and exact connection set, and every tool
but submit_repair_candidate is read-only. That tool ships in the next MCP
server release. New hosted authorization reviews the exact mode and connection
selection in browser consent. A zero-connection grant returns empty lists.
Every tool result and resource wraps its payload in the same envelope, so the client always knows which workspace the data came from. Counts and latest activity in the overview include only the reviewed mode and connections:
Code example
{ "schemaVersion": "seamward.mcp/1", "workspace": { "id": "wks_2ac9017e", "name": "Acme", "slug": "acme" }, "data": { "...": "the tool-specific result" }}Tools
| Tool | Purpose | Required scope |
|---|---|---|
get_workspace_overview | Workspace summary, integration health, incident counts | seamward:workspace:read |
list_integrations | Page through integrations with health and both analysis states | seamward:workspace:read |
get_integration | One integration with safe configuration, both analysis states, and the credential expiry dates your team recorded | seamward:workspace:read |
list_incidents | Page through incidents, optionally filtered by status | seamward:incidents:read |
get_incident | One incident with findings and evidence references | seamward:incidents:read |
get_incident_replay | Replay dataset metadata and deterministic run results | seamward:repairs:read |
get_incident_evidence_bundle | The case file for one incident, before any proposal: findings, expected outcome, mapped repository, replay datasets, and the commands that check a fix | seamward:incidents:read |
get_incident_impact | A plain summary of one incident built only from counted evidence, how many affected records have recovered, and the affected accounts as keyed hashes with counts | seamward:incidents:read |
list_affected_records | A page of one incident's affected records as keyed hashes, each with its status. Every call is recorded in the workspace audit log | seamward:incidents:read |
list_advisories | What is coming for the selected connections before it breaks anything: a provider deprecation and its end date, a change in a watched published contract, or a recorded credential date drawing near. Soonest first, up to 50 items | seamward:incidents:read |
get_repair_proposal | One proposal with validation and decision provenance | seamward:repairs:read |
submit_repair_candidate | Records a fix made in your repository as a proposal awaiting approval, backed by a passed run your runner reported. The only tool that writes | seamward:repairs:propose |
get_approved_repair_bundle | Resource links for an approved repair bundle | seamward:repairs:export |
Parameters
The two list tools share pagination parameters:
| Parameter | Type | Constraints |
|---|---|---|
cursor | string, optional | 1 to 512 characters; omit for the first page |
limit | integer, optional | 1 to 100, default 25 |
The remaining tools each take one identifier:
| Parameter | Used by | Format |
|---|---|---|
integrationId | get_integration | Starts with int_ |
incidentId | get_incident, get_incident_replay, get_incident_evidence_bundle, get_incident_impact, list_affected_records | Opaque string, 1 to 128 characters |
proposalId | get_repair_proposal, get_approved_repair_bundle | Starts with rep_ |
incidentId, runId, repository, ref, pullRequestUrl | submit_repair_candidate | See Submit a repair candidate |
status | list_incidents, optional | open or resolved |
status | list_advisories, optional | active (default) or all |
status | list_affected_records, optional | missing or recovered; affected or cleared for an incident about duplicated or out-of-order records |
cursor, limit | list_affected_records, optional | limit is 1 to 200, default 100; cursor is the previous page's nextCursor |
get_workspace_overview takes no parameters. All tool inputs are strict: an unknown parameter is rejected rather than ignored.
Example call
A client listing open incidents sends:
Code example
{ "name": "list_incidents", "arguments": { "status": "open", "limit": 10 }}and receives the standard envelope with a page of incidents in data, including a cursor when more pages exist. Identifiers in results (such as incidentId values) feed directly into the single-item tools.
Impact and affected records
get_incident_impact and list_affected_records return what the console's Impact and recovery card and the CLI export return, so an agent can say how far an incident reaches and which records are left. Records and accounts are keyed hashes. Seamward does not hold your identifiers, so an agent cannot name a customer from these results; your team resolves the hashes with its own key, as Recovery describes.
Code example
{ "name": "list_affected_records", "arguments": { "incidentId": "inc_example", "status": "missing", "limit": 50 }}data is one page of the seamward.affected-records/1 document: totals for the whole incident, records, and nextCursor when more remain. Neither tool re-sends an event or changes anything.
Submit a repair candidate
submit_repair_candidate is the one tool that writes. It does what seamward repairs submit does, with the same checks, so an agent that made a fix and ran your replay runner can hand the result in for review.
Code example
{ "name": "submit_repair_candidate", "arguments": { "incidentId": "inc_example", "runId": "rrun_example", "repository": "acme/billing-service", "ref": "fix/invoice-idempotency", "pullRequestUrl": "https://github.com/acme/billing-service/pull/42" }}| Parameter | Rule |
|---|---|
incidentId | An incident inside the grant's mode and connections |
runId | A run your runner reported for this incident, labelled candidate |
repository | owner/name |
ref | The branch or ref the change is on, up to 255 characters |
pullRequestUrl | Optional https address of the pull request |
What it can and cannot do:
- It adds one proposal, awaiting approval. It cannot approve, reject, merge, deliver or deploy. Approval stays a recorded decision by an owner or admin in the console.
- The run is the proof, not the agent's word. The run must have passed, on a committed change with a clean working tree. The commit recorded on the proposal is the run's commit.
- It needs
seamward:repairs:propose, which a client must request and you must approve, and the member who authorized the client must be an owner or admin. A grant with every read scope still cannot call it. - It is bounded. One run backs one proposal, so repeating a call returns the same proposal, and an incident accepts at most 20 submitted candidates.
- Each new proposal is written to the audit log with the member who authorized the client.
A refusal is returned as data: {"ok": false, "error": "..."} with one of replay_run_not_found, repair_candidate_run_not_candidate, repair_candidate_not_validated, repair_candidate_commit_required or repair_candidate_limit_reached. Text in a submission (the repository, ref and address) is shown to reviewers as data.
Credential expiry in get_integration
get_integration includes credentialExpiry: one entry per expiry date your team recorded for the connection under connection health. Each entry is a kind, a name and a date. Seamward does not store credentials, so there is no credential in the result.
Code example
{ "credentialExpiry": [ { "kind": "signing-secret", "label": "Webhook signing secret", "expiresAt": "2026-11-01T00:00:00.000Z", "warnDays": 30 } ]}kind is provider-token, signing-secret, certificate, api-key or other. warnDays is how far ahead of expiresAt the advisory is raised. The list is empty when no dates are recorded. The advisory itself, once raised, is returned by list_advisories.
Tool errors
Failed calls return a stable error code instead of data:
| Code | Meaning | What to do |
|---|---|---|
unauthorized | The grant is no longer valid for this workspace | Reconnect and approve again |
forbidden | The grant lacks the tool's required scope | Reconnect and approve the missing scope |
not_found | The id is outside the reviewed selection or no longer exists | Check the id, mode and connection set |
internal_error | Something failed on the Seamward side | Retry; report it if it persists |
get_approved_repair_bundle additionally requires that the proposal is already approved and passes fingerprint checks; an unapproved proposal is never exported.
Resources
Clients that browse resources can read the same data by URI:
| Resource URI | Contents | Required scope |
|---|---|---|
seamward://workspace/current/overview | Workspace health summary | seamward:workspace:read |
seamward://workspace/current/integrations/{integrationId} | One integration | seamward:workspace:read |
seamward://workspace/current/incidents/{incidentId} | One incident with redacted evidence | seamward:incidents:read |
seamward://workspace/current/incidents/{incidentId}/replay | Immutable replay evidence | seamward:repairs:read |
seamward://workspace/current/repairs/{proposalId} | One repair proposal and validation record | seamward:repairs:read |
seamward://workspace/current/repairs/{proposalId}/export/{fileName} | One file from an approved repair bundle | seamward:repairs:export |
The export resource serves three files per approved proposal: repair.json (the machine-readable manifest), REPAIR.md (the readable report), and repair.ts (the TypeScript patch). All resources return JSON except the export files, which are served as text.
Prompts
Two prompts package common workflows so you can start them from your client's prompt picker:
investigate_seamward_incidenttakes anincidentIdand guides an evidence-backed investigation: read the incident and its replay evidence, inspect your local repository separately, and keep Seamward evidence distinct from inference. It never changes production systems.implement_approved_repairtakes aproposalIdand guides a local review change: confirm the proposal is approved, retrieve its bundle, and prepare a local patch with tests. It never merges or deploys.
Neither prompt can approve, deliver, or mutate anything in Seamward; they direct the client to the read tools above.
Next steps
- Authorization: which scopes unlock these tools and how to revoke a client.
- MCP overview: connecting a client for the first time.
Integration list and detail results include structuralAnalysis and behavioralAnalysis with its current
status, last completed pass and any capacity pause. The object follows the
Workspace API state definition. Observation activity or zero
open incidents alone does not prove that both forms of analysis completed.