# Mode: HTTP + bearer token

For MCP servers that authenticate via a static `Authorization: Bearer <token>` header. mcporter reads the token from an env var per request — no install hook needed, no OAuth vault.

## When to pick this mode

- The MCP requires a single static credential (an API key, personal access token, etc.).
- That credential is sent via `Authorization: Bearer <token>`.
- There's no OAuth dance, no token rotation requirement at the MCP layer.

If the MCP doesn't have `/.well-known/oauth-authorization-server`, doesn't list a `registration_endpoint`, and the docs say "send your API key as a Bearer token", this is the right mode.

## 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.**
- **Env-var name** — what env var the user will set the bearer token to. Convention: uppercased slug + `_TOKEN` or `_API_KEY`. Slug `acme-stuff` → `ACME_STUFF_TOKEN`.

If the user doesn't specify the env-var name, propose one based on the slug and confirm.

## Files to generate

Standard non-OAuth shape — see [`conventions.md` § "Files generated by scaffolding"](conventions.md#files-generated-by-scaffolding). No `scripts/` directory. mcporter resolves the bearer token from env per request, so there is no install-time setup.

## 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": ["<TOKEN_ENV>"],
          },
        "primaryEnv": "<TOKEN_ENV>",
        "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 `<TOKEN_ENV>` to be set in the agent's runtime environment. mcporter sends it as `Authorization: Bearer <value>` on every request.

If calls fail with auth errors, the token is invalid or revoked — re-issue and re-set `<TOKEN_ENV>`. There is no automatic refresh; bearer tokens are static.
````

**Substitutions to make before writing the SKILL.md.** Substitute `<SLUG>`, `<BASE_URL>`, and `<TOKEN_ENV>` (the bearer-token env var name — see [§ "Required inputs"](#required-inputs) above) throughout the template. The "no automatic refresh; bearer tokens are static" sentence is part of the canonical contract; keep it even when it feels redundant.

**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",
      "bearerTokenEnv": "<TOKEN_ENV>"
    }
  }
}
```

mcporter reads `bearerTokenEnv` per request ([upstream src/runtime/transport.ts](https://github.com/openclaw/mcporter/blob/main/src/runtime/transport.ts)), so token rotation is "set the env var to a new value" — no skill-side state to update.

## Mode-specific validation

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

- [ ] `mcpServers.<slug>.transport` = `"http"` and `bearerTokenEnv` is set.
- [ ] `mcpServers.<slug>` has **no** `auth: "oauth"` field. (If present, you've cross-pollinated with the OAuth template.)
- [ ] `requires.env` contains exactly the env var named in `bearerTokenEnv`.
- [ ] `primaryEnv` = `<TOKEN_ENV>`.
- [ ] No `scripts/` directory exists. (Bearer mode has no install hook.)

## Reporting back to the user

Follow the universal shape in [`conventions.md` § "Reporting back to the user"](conventions.md#reporting-back-to-the-user). Bearer-specific note: the smoke test needs `<TOKEN_ENV>` set in the invoking environment, e.g. `<TOKEN_ENV>=... mcporter --config <out>/<slug>/mcporter.json list <slug> --schema`.

## References

- [RFC 6750 — The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750) — the `Authorization: Bearer <token>` semantics this mode implements
- [openclaw/mcporter — `src/runtime/transport.ts`](https://github.com/openclaw/mcporter/blob/main/src/runtime/transport.ts) — implementation of `bearerTokenEnv` resolution per request
- [openclaw/mcporter — `docs/config.md` § "Configuration Guide"](https://github.com/openclaw/mcporter/blob/main/docs/config.md) — `bearerTokenEnv` config field reference