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

# List and create MCP sources over the Armature REST API

> Inventory active MCP sources for your organization and register new HTTP, SSE, or hosted stdio sources from scripts and infrastructure-as-code.

The `/mcp-servers` endpoints expose Armature's MCP source catalog. Use them to inventory the sources connected to your organization, register new sources from infrastructure-as-code, or look up a specific source before creating a workflow against it.

All paths in this page are relative to the [REST API base URL](/rest-api/overview#base-url). All requests require an [API key](/rest-api/authentication).

## List MCP sources

```http theme={null}
GET /mcp-servers
```

Returns active production MCP sources for your organization.

**Query parameters**

| Parameter      | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `category`     | One or more category slugs. Comma-separated values are accepted. |
| `categorySlug` | Alternative single-slug filter.                                  |

**Example**

```bash theme={null}
curl https://your-org.armature.app/api/armature/v1/mcp-servers \
  -H "Authorization: Bearer amt_<key-id>_<secret>"
```

**Response**

```json theme={null}
{
  "rows": [
    {
      "id": "mcp_…",
      "name": "Production GitHub MCP",
      "transport_type": "streamable_http",
      "base_url": "https://github-mcp.example.com",
      "categories": ["dev-tools"]
    }
  ]
}
```

## Get one MCP source

```http theme={null}
GET /mcp-servers/{id}
```

Returns the full record for a single source.

```bash theme={null}
curl https://your-org.armature.app/api/armature/v1/mcp-servers/{id} \
  -H "Authorization: Bearer amt_<key-id>_<secret>"
```

## Create an MCP source

```http theme={null}
POST /mcp-servers
```

Registers a new MCP source. Requires `editor`, `admin`, or `owner`.

**Request body**

| Field              | Type         | Required | Description                                                   |
| ------------------ | ------------ | -------- | ------------------------------------------------------------- |
| `name`             | string       | yes      | Display name shown in the dashboard.                          |
| `transportType`    | string       | —        | `streamable_http`, `sse`, or `stdio_hosted`.                  |
| `targetKind`       | string       | —        | `mcp` or `cli`.                                               |
| `baseUrl`          | string (URI) | —        | Endpoint URL for HTTP and SSE transports.                     |
| `connectionConfig` | object       | —        | Transport-specific configuration.                             |
| `networkPolicy`    | object       | —        | Network policy for hosted or CLI targets.                     |
| `authProfile`      | object       | —        | Optional default auth profile to create alongside the source. |
| `environment`      | string       | —        | Defaults to `production`.                                     |

**Example**

```bash theme={null}
curl https://your-org.armature.app/api/armature/v1/mcp-servers \
  -H "Authorization: Bearer amt_<key-id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production GitHub MCP",
    "transportType": "streamable_http",
    "targetKind": "mcp",
    "baseUrl": "https://github-mcp.example.com",
    "authProfile": {
      "name": "default",
      "authType": "bearer_token",
      "authConfig": { "header_name": "Authorization" }
    }
  }'
```

**Response (`201 Created`)**

```json theme={null}
{
  "server": { "id": "mcp_…", "name": "Production GitHub MCP" },
  "authProfile": { "id": "auth_…", "name": "default" },
  "discoveryJob": { "id": "job_…", "status": "queued" },
  "provisioningJob": null
}
```

If the source is hosted or backed by a CLI binary, Armature also queues a discovery and (when relevant) a provisioning job. The IDs in the response can be used to poll job status from the dashboard.

<Warning>
  Never put plaintext credentials in `authConfig`. Configure the auth profile in the dashboard after creation, or reference a managed secret. See [Connecting an MCP source](/mcp-servers/connecting) for the supported auth types.
</Warning>

## Related

* [Connecting an MCP source](/mcp-servers/connecting) — UI walkthrough and supported transports.
* [Create a workflow](/rest-api/workflows) — point a workflow at a registered source.