> ## 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.

# Product MCP: turn your API into a hosted MCP server

> Publish your product API as an Armature-hosted MCP server. Callers authenticate with their own product credential, which Armature validates and forwards upstream.

A **Product MCP** turns your existing product API into an MCP server that Armature hosts for you. Upload an OpenAPI document, configure how callers authenticate, and Armature publishes a public MCP endpoint at:

```text theme={null}
https://mcp.<org-slug>.armature.tech/<source-slug>
```

Callers — coding assistants, in-app agents, internal tools — connect with **their own product API credential**. Armature validates that credential against your API and forwards it upstream on every tool call. You never issue or manage a second end-user credential.

## When to use Product MCP

Use a Product MCP when you want to give your customers and their AI agents an MCP front door to your product without building and operating an MCP server yourself.

* **You already have an HTTP API** documented with OpenAPI and a way to authenticate users (bearer token, API key header, or query parameter).
* **You want to expose that API as MCP tools** without maintaining a separate MCP service, transport layer, or tool catalog.
* **Your callers should authenticate as themselves** — using whatever credential they already use against your product — rather than through an Armature-issued token.

If instead you are testing or monitoring an MCP server you operate, see [Connecting an MCP server](/mcp-servers/connecting).

## How it works

```text theme={null}
caller ──► mcp.<org-slug>.armature.tech/<source-slug> ──► your product API
           (Armature host)                                 (your upstream)

           ▲                                               ▲
           │  caller's product credential extracted        │  same credential
           │  per your auth config and validated           │  forwarded upstream
```

1. The caller sends an MCP request to your public Product MCP URL and includes their product API credential in the header or query parameter you configured.
2. Armature extracts the credential, validates it against your product API (if you opted into validation), and serves `tools/list` plus the OpenAPI-derived tool schemas.
3. When the caller invokes a tool, Armature dispatches an HTTP call against your upstream API, forwarding the caller's credential in the location and format you configured.

Raw credentials are never stored, logged, or passed into any sandboxed code. Armature keeps an in-memory validation cache keyed by a one-way fingerprint of the credential, never the credential itself.

## What you configure

Every Product MCP has four parts you manage from the **Product MCPs** page in the dashboard.

<CardGroup cols={2}>
  <Card title="Endpoint" icon="globe">
    A **name** and a **slug**. The slug becomes the path on `mcp.<org-slug>.armature.tech/<slug>`. The base URL points at your product API (must be `https://`).
  </Card>

  <Card title="API docs" icon="file-code">
    An **OpenAPI document** that describes the operations you want to expose. Armature parses it into MCP tools, capability descriptions, and a search index. Re-upload to refresh.
  </Card>

  <Card title="API Connection" icon="key">
    How callers send their credential to your MCP endpoint, and how Armature forwards it upstream. Configurable per endpoint.
  </Card>

  <Card title="Activation" icon="power-off">
    A Product MCP only goes live after API docs and an API Connection are both configured. You can pause and resume it at any time.
  </Card>
</CardGroup>

## Authentication modes

When you configure the **API Connection**, you pick:

* **Credential location** — where the caller sends their credential. Either an HTTP header (default `Authorization`) or a query parameter (default `api_key`).
* **Token format** — `bearer` (expects `Bearer <token>`) or `raw` (the value as-is).
* **Upstream forwarding** — `same` to forward the credential to the upstream API in the same location and format the caller used, or `custom` to remap it to a different header/parameter and format.
* **Validation mode** — see below.

### Validation modes

| Mode                              | What Armature does                                                                                                                                                       | When to use                                                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `validate_before_tools` (default) | Calls your **validation endpoint** with the caller's credential before serving `tools/list` or any tool call. Bad credentials get `401` and never see your tool catalog. | Recommended for all production deployments.                                                                  |
| `presence_only`                   | Accepts any well-formed credential and forwards it upstream without validating. Your upstream API is the only line of defense.                                           | Only when you cannot expose a validation endpoint. Requires explicit confirmation of the security trade-off. |

<Warning>
  `presence_only` means anyone with the Product MCP URL can send a fake credential and read your tool catalog and capability descriptions. Use `validate_before_tools` whenever your API exposes any "who am I" or token-introspection endpoint.
</Warning>

The validation endpoint must live on the same origin as your configured base URL. Armature treats `2xx` as valid, `401`/`403` as invalid, and network failures or `5xx` as fail-closed (`503` to the caller).

## Example: configuring a Product MCP

This example exposes the API behind `https://api.acme.example.com` as a Product MCP. Callers send `Authorization: Bearer <token>`; Armature validates the token against `/v1/me` before serving tools and forwards the same header upstream.

```json theme={null}
{
  "name": "Acme Public API",
  "sourceSlug": "acme",
  "baseUrl": "https://api.acme.example.com",
  "authentication": {
    "credentialLocation": "header",
    "credentialName": "Authorization",
    "tokenFormat": "bearer",
    "validationMode": "validate_before_tools",
    "validationEndpoint": "https://api.acme.example.com/v1/me",
    "upstreamForwarding": { "mode": "same" }
  }
}
```

Once API docs are uploaded and the endpoint is activated, the public MCP URL is:

```text theme={null}
https://mcp.acme.armature.tech/acme
```

A caller connects with their own Acme API token:

```http theme={null}
POST https://mcp.acme.armature.tech/acme HTTP/1.1
Authorization: Bearer caller-acme-token
Content-Type: application/json

{ "jsonrpc": "2.0", "method": "tools/list", "id": 1 }
```

## Next steps

See [Set up a Product MCP](/product-mcp/setup) for the step-by-step dashboard flow, including uploading OpenAPI documents, configuring authentication, and activating the public endpoint.