# Mode: HTTP + custom headers

For MCP servers that authenticate via custom HTTP headers (`X-API-Key`, `Authorization` with a non-Bearer scheme, multiple headers, etc.). mcporter resolves `${VAR}` placeholders in headers per request.

## When to pick this mode

- The MCP needs a header that isn't `Authorization: Bearer <token>` (the bearer mode covers that case).
- Or it needs more than one header (token + tenant ID, for example).
- Or it needs an `Authorization` scheme other than `Bearer` (`Basic`, `Token`, etc.).

## Required inputs

In addition to the universal `<slug>` and `--out <path>` (covered in [SKILL.md § "Step 2"](../SKILL.md)):

- `<base-url>` — the MCP endpoint, e.g. `https://api.example.com/mcp`. **HTTPS only.**
- **One or more `<HEADER_NAME>=<ENV_VAR_NAME>` pairs.** Example: `X-API-Key=ACME_API_KEY`, `X-Tenant-ID=ACME_TENANT_ID`. Header names follow HTTP conventions; env var names should be uppercase + underscores and ideally prefixed with the slug's uppercase form for clarity.

If the user gives a partial spec (header name without env-var name, or vice versa), ask for the missing piece. Don't assume.

## Files to generate

Standard non-OAuth shape — see [`conventions.md` § "Files generated by scaffolding"](conventions.md#files-generated-by-scaffolding). No `scripts/` directory.

## Template — `<slug>/SKILL.md`

````markdown
---
name: <SLUG>
description: "TODO: rewrite before publishing — durable purpose framing for this MCP integration."
homepage: "TODO: replace with upstream MCP docs URL"
metadata:
  {
    "openclaw":
      {
        "emoji": "📡",
        "requires":
          {
            "bins": ["mcporter"],
            "env": [<EACH_ENV_VAR_NAME_FROM_HEADERS>],
          },
        "primaryEnv": "<MOST_REPRESENTATIVE_ENV_VAR>",
        "install":
          [
            {
              "id": "node",
              "kind": "node",
              "package": "mcporter",
              "bins": ["mcporter"],
              "label": "Install mcporter (node)",
            },
          ],
      },
  }
---

# <SLUG>

## How to use this skill

This skill is a thin pass-through to the hosted MCP server at `<BASE_URL>`. The live server is the source of truth for what tools exist, what they're called, what arguments they take, and any per-server instructions the server publishes.

**Step 1 — Discover the live tool catalog and any server-published usage instructions.** Always run this first; do not rely on tool names from memory:

```sh
mcporter --config {baseDir}/mcporter.json list <SLUG> --schema
```

The output includes the server's `Instructions:` field (read it) and a JSON Schema for every tool's parameters. Treat this as the authoritative reference for the rest of the session.

**Step 2 — Call any tool from the catalog** using the form `<SLUG>.<tool>`:

```sh
mcporter --config {baseDir}/mcporter.json call <SLUG>.<tool> <arg>=<value> ...
```

Add `--output json` for structured output (also surfaces transport errors as JSON envelopes):

```sh
mcporter --config {baseDir}/mcporter.json call --output json <SLUG>.<tool> ...
```

## Authentication

This skill expects the following env vars to be set in the agent's runtime environment:

- **`<ENV_VAR_NAME>`** — sent as the `<HEADER_NAME>` request header.

mcporter resolves these per request. If calls fail with auth errors, the credentials are invalid — re-issue them and re-set the env vars.
````

**Substitutions to make before writing the SKILL.md.** Substitute `<SLUG>` and `<BASE_URL>` throughout. The Authentication block contains a single example bullet (`<ENV_VAR_NAME>` / `<HEADER_NAME>`); for each `<HEADER_NAME>=<ENV_VAR_NAME>` pair the user provided, *duplicate that bullet* with the pair's values substituted (this counts as required expansion, not an edit).

**Editability rules** for the Discovery flow and Authentication block live in [`conventions.md` § "Editability — Discovery flow and Authentication block"](conventions.md#editability--discovery-flow-and-authentication-block). Read it before publishing.

**Optional sections.** Between the discovery flow and the Authentication block, you *may* insert `## Conventions worth knowing` and/or `## Safety` sections if they apply to this MCP. Their templates and inclusion criteria live in [`conventions.md` § "Optional sections — Conventions worth knowing & Safety"](conventions.md#optional-sections--conventions-worth-knowing--safety). Omit entirely if they don't apply.

## Template — `<slug>/mcporter.json`

```json
{
  "imports": [],
  "mcpServers": {
    "<SLUG>": {
      "baseUrl": "<BASE_URL>",
      "transport": "http",
      "headers": {
        "<HEADER_NAME_1>": "${<ENV_VAR_NAME_1>}",
        "<HEADER_NAME_2>": "${<ENV_VAR_NAME_2>}"
      }
    }
  }
}
```

mcporter expands `${VAR}` from process env at request time per [upstream config docs](https://github.com/openclaw/mcporter/blob/main/docs/config.md). The placeholder syntax is `${...}`, not `$VAR` — the braces are required for the parser.

For headers that prefix the env value with a literal scheme (`Authorization: Token ${API_TOKEN}`), keep the prefix in the JSON value:

```json
"headers": {
  "Authorization": "Token ${API_TOKEN}"
}
```

## Mode-specific validation

In addition to the universal checks in `validation.md`:

- [ ] `mcpServers.<slug>.transport` = `"http"` and `headers` is set.
- [ ] `mcpServers.<slug>` has **no** `auth: "oauth"` field and **no** `bearerTokenEnv` field. (If present, you've cross-pollinated with another template.)
- [ ] Every `${VAR}` referenced in `headers` values appears in `requires.env`.
- [ ] No env var appears in `requires.env` that isn't referenced in `headers`. (Stale requirements gate skill loading on credentials the skill never uses.)
- [ ] `primaryEnv` is one of the env vars in `requires.env`.
- [ ] No `scripts/` directory exists.

## Reporting back to the user

Follow the universal shape in [`conventions.md` § "Reporting back to the user"](conventions.md#reporting-back-to-the-user). Headers-specific note: every env var referenced by `headers` interpolations must be set before the smoke test — list them by name so the user knows what to populate.

## References

- [openclaw/mcporter — `docs/config.md`](https://github.com/openclaw/mcporter/blob/main/docs/config.md) — `headers` config field semantics and `${VAR}` interpolation rules
- [openclaw/mcporter — `src/env.ts`](https://github.com/openclaw/mcporter/blob/main/src/env.ts) — env-var placeholder expansion implementation
- [openclaw/mcporter — `mcporter.schema.json`](https://github.com/openclaw/mcporter/blob/main/mcporter.schema.json) — authoritative JSON Schema for `mcporter.json`, including the `headers` field shape
- [RFC 7235 — HTTP Authentication](https://datatracker.ietf.org/doc/html/rfc7235) — the `Authorization` header conventions referenced when using non-Bearer schemes