# HereGo MCP Server

The preferred way for AI agents to request visual evidence. A public, stateless adapter over the REST API — no MCP-level authentication, no account, no API key. Request-scoped access tokens travel with the agent as tool arguments.

## Endpoint

`https://herego.video/mcp`

Point any MCP client at the endpoint above. Machine-readable capabilities live at
https://herego.video/.well-known/mcp/server-card.json.

## Client configuration

```json
{
  "mcpServers": {
    "herego": {
      "url": "https://herego.video/mcp"
    }
  }
}
```

## Tools

Three tools cover the full lifecycle: request → check & retrieve → delete.

### `request_video_evidence` — Generate video submission request

Generate a video submission request for a person to provide visual evidence. Use it when you need to see what is happening rather than relying on a textual description — diagnosing a UI bug, understanding a browser workflow, investigating a physical-world problem, or collecting evidence that text or screenshots cannot describe. This does not record or create a video; it creates a request and returns a submission_url to send to the human (they record in a browser — no app install or HereGo account needed) plus a request-scoped access_token. Retain the access_token: it is required by get_video_evidence and delete_video_request.

Tell the user: "Generating a video submission request" / "Generating a request for the user to submit video evidence".
Never say: "recording a video" / "creating a recording".

**Arguments**

- `prompt` (string, required): Instruction shown to the human recording the evidence. 1–2000 characters.
- `expires_in_hours` (integer, required): Number of hours until the request expires. Must be between 1 and 48.

**Returns**

- `id` (string, required): The HereGo request identifier, e.g. req_abc123.
- `status` (awaiting_submission, required): A fresh request always starts out awaiting human submission.
- `submission_url` (string (url), required): Shareable link to send directly to the human for recording.
- `access_token` (string, required): Request-scoped bearer token. Retain it — it authenticates get_video_evidence and delete_video_request. Never ask the human for it.
- `expires_at` (string (datetime), required): ISO timestamp after which the request can no longer be submitted to.

**Example call**

```json
{
  "prompt": "Please show me what happens when you try to check out.",
  "expires_in_hours": 24
}
```

**Example result**

```json
{
  "id": "req_abc123",
  "status": "awaiting_submission",
  "submission_url": "https://herego.video/r/abc123",
  "access_token": "rat_9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
  "expires_at": "2026-09-08T14:30:00Z"
}
```

> Each call creates a brand-new request with its own access_token — tokens are not interchangeable between requests.

### `get_video_evidence` — Check video submission status and retrieve video

Authoritatively check a video submission request and retrieve the submitted video. Workflow: first call request_video_evidence, give the human its submission_url, and retain the returned access_token. Then call this tool with that request_id and access_token. The access_token is passed as a tool argument and forwarded to the underlying REST APIs — do not ask the human for it and never send it as an MCP HTTP header. If the status is awaiting_submission, wait and poll again when appropriate. When the status is submitted, consume the returned MCP media content to inspect the actual video, not a webpage URL. Expired or deleted requests return status expired successfully, never an error.

Tell the user: "Checking the video submission status" / "Retrieving the submitted video evidence".
Never say: "recording a video" / "watching the recording".

**Arguments**

- `request_id` (string, required): HereGo request ID returned by request_video_evidence.
- `access_token` (string, required): Request-scoped bearer token returned by request_video_evidence. Retain and reuse it rather than asking the human for a token.

**Returns**

- `request_id` (string, required): Echo of the requested HereGo request identifier.
- `status` (awaiting_submission | submitted | expired, required): Current lifecycle state of the request.
- `expires_at` (string (datetime), optional): Present when the request carries an expiry timestamp.
- `video` (object, optional): Present only when submitted. Carries mime_type and size, alongside the video itself as MCP media content.

**Example call**

```json
{
  "request_id": "req_abc123",
  "access_token": "rat_9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}
```

**Example result**

```json
{
  "request_id": "req_abc123",
  "status": "submitted",
  "expires_at": "2026-09-08T14:30:00Z",
  "video": {
    "mime_type": "video/webm",
    "size": 482113
  }
}
// + the actual video attached as MCP media content
```

> While awaiting_submission, the tool returns a plain-text notice — no video is available yet, so wait and call again.
> Always inspect the attached MCP media content for submitted videos; there is no webpage URL to open.

### `delete_video_request` — Delete video request

Delete an entire HereGo video request, including any associated submitted video. Call with the request_id and the request-scoped access_token returned by request_video_evidence. Use it when the evidence is no longer needed, was requested in error, or must be removed for privacy. This deletes the entire request, not just a submitted video.

Tell the user: "Deleting the video request" / "Deleting the request for video evidence and its submitted video".
Never say: "deleting the recording" / "stopping the recording".

**Arguments**

- `request_id` (string, required): HereGo request identifier to delete.
- `access_token` (string, required): Request-scoped bearer token returned by request_video_evidence.

**Returns**

- `request_id` (string, required): Echo of the deleted HereGo request identifier.
- `deleted` (boolean, required): Always true on success — the request and its video are gone.

**Example call**

```json
{
  "request_id": "req_abc123",
  "access_token": "rat_9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}
```

**Example result**

```json
{
  "request_id": "req_abc123",
  "deleted": true
}
```

> Deletion is permanent. Afterward, get_video_evidence for the same id returns expired.

## Agent workflow

1. Call `request_video_evidence` with an instruction for the human.
2. Give the human the returned `submission_url`.
3. Retain the returned `access_token`; never ask the human for it.
4. Call `get_video_evidence` with the `request_id` and `access_token` to check status.
5. If the status is `awaiting_submission`, wait and poll again when appropriate.
6. When the status is `submitted`, consume the returned MCP media content — the actual video, not a webpage URL.

## Statuses

- `awaiting_submission`: the human has not submitted yet. Wait and poll `get_video_evidence` again.
- `submitted`: video received. The actual video is attached as MCP media content.
- `expired`: the request expired or was deleted. No video is available — create a new request instead.

## Authentication

The MCP server itself requires no authentication. The `get_video_evidence` and `delete_video_request` tools take request-scoped access tokens as tool arguments; the server forwards them to the REST APIs as `Authorization: Bearer <token>`. Never send tokens as MCP HTTP headers.

## Further reading

- REST API documentation: https://herego.video/docs/api
- OpenAPI specification: https://herego.video/api/openapi.json
- Agent quickstart: https://herego.video/llms.txt