> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP upload status API

> Poll the build of an uploaded MCP server until it succeeds or fails.

When you upload an MCP server with `POST /api/mcp/connectors/upload` (a zip) or `POST /api/mcp/connectors/upload-github`, the server queues a build and answers `202` with a `build_id`. Use that `build_id` with the route on this page to follow the build to the end. Upload guide: [Deploy an MCP server](https://docs.nasiko.com/build/mcp/deploy-server.md).

The CLI does this for you: [`nasiko mcp connector upload`](https://docs.nasiko.com/reference/cli/mcp) waits on this route and prints each state change.

## Authentication

Send the session JWT from [`POST /api/auth/login`](https://docs.nasiko.com/api-reference/account) as `Authorization: Bearer <token>`, or use the dashboard cookie. Any authenticated user can call it, but only for their own uploads. A superuser can read any upload.

## Endpoints

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/api/mcp/connectors/uploads/{upload_id}` | Status of one MCP server upload |

***

## Get upload status

`GET /api/mcp/connectors/uploads/{upload_id}`

Returns the current state of one upload's build. Poll it after an upload until `status` is `success` or `failed`.

Prefer this route over `GET /api/mcp/connectors/{id}/build-status` for polling. If a **first-time** upload fails, the connector is removed so you can re-upload under the same name, and the connector-scoped route then returns `404`. This route keeps answering for the upload either way.

**Auth:** session JWT or dashboard cookie. **Role:** the user who uploaded, or a superuser.

### Path parameters

| Name | Type | Description |
| - | - | - |
| `upload_id` | string | The `build_id` returned by the upload request |

### Example

Upload, then poll:

```bash theme={null}
curl -X POST https://<your-host>/api/mcp/connectors/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F name=my-mcp-server \
  -F version_tag=v1 \
  -F source=@my-mcp-server.zip
# → { "data": { "connector_id": "a1b2c3d4-...", "build_id": "e5f6a7b8-..." }, "status_code": 202, ... }

curl https://<your-host>/api/mcp/connectors/uploads/e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "upload_id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
    "connector_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "connector_name": "my-mcp-server",
    "status": "building",
    "error_message": null
  },
  "status_code": 200,
  "message": "upload status retrieved successfully"
}
```

A failed build:

```json theme={null}
{
  "data": {
    "upload_id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
    "connector_id": null,
    "connector_name": "my-mcp-server",
    "status": "failed",
    "error_message": "readiness check failed after exhausting retries"
  },
  "status_code": 200,
  "message": "upload status retrieved successfully"
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `upload_id` | string | The ID you polled with |
| `connector_id` | UUID or null | The connector this upload builds. `null` once the connector has been removed — for example after a failed first-time upload |
| `connector_name` | string | The `name` you uploaded under |
| `status` | string | See the states below |
| `error_message` | string or null | Why the build failed. Set only when `status` is `failed` |

### States

| `status` | Meaning | Terminal |
| - | - | - |
| `pending` | Queued, not started | No |
| `building` | The image is being built and deployed | No |
| `success` | Built and deployed. The connector is live | Yes |
| `failed` | The build or deploy failed. Read `error_message` | Yes |

A build that stops without finishing is marked `failed` with the message `build job did not complete`.

### Errors

Errors use the envelope `{ "data": null, "status_code": <n>, "message": "..." }`.

| Status | `message` | When |
| - | - | - |
| `401` | `invalid user id in identity`, or an authentication message | No valid session |
| `403` | `this upload does not belong to you` | Someone else's upload, and you aren't a superuser |
| `404` | `upload '<upload_id>' not found` | Unknown `upload_id` |
| `500` | `internal error` | Server-side failure |

### Notes

* Read-only and safe to call repeatedly. There's no push notification or stream; poll on an interval. The CLI polls every 2 seconds.
* The `connector_id` returned by the upload stays useful for [build logs](https://docs.nasiko.com/build/mcp/deploy-server.md#watch-it-build) while the connector exists.

## Related

* [Deploy an MCP server](https://docs.nasiko.com/build/mcp/deploy-server.md)
* [MCP gateway](https://docs.nasiko.com/build/mcp/overview.md)
* [`nasiko mcp` CLI reference](https://docs.nasiko.com/reference/cli/mcp)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.