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

# Developer Guide

> Set up and run Context7 MCP locally for development

This guide covers how to set up the Context7 MCP server locally for development and testing.

## Getting Started

Clone the project and install dependencies:

```bash theme={null}
git clone https://github.com/upstash/context7.git
cd context7
pnpm i
```

Build:

```bash theme={null}
pnpm run build
```

Run the server:

```bash theme={null}
node packages/mcp/dist/index.js
```

## CLI Arguments

`context7-mcp` accepts the following CLI flags:

| Flag | Description | Default |
| - | - | - |
| `--transport <stdio\|http>` | Transport to use. Use `http` for remote HTTP server or `stdio` for local integration. | `stdio` |
| `--port <number>` | Port to listen on when using `http` transport. `0` picks a free port. | `3000` |
| `--api-key <key>` | API key for authentication (or set `CONTEXT7_API_KEY` env var). | - |

> [!NOTE]
>
> Get your API key by creating an account at
> [context7.com/dashboard](https://context7.com/dashboard?tab=settings).

### Examples

HTTP transport on port 8080:

```bash theme={null}
node packages/mcp/dist/index.js --transport http --port 8080
```

HTTP transport requires a credential on every request by default. Clients send `Authorization: Bearer YOUR_API_KEY`. Set `MCP_AUTH_ENFORCEMENT=observe` to also accept requests without credentials on `/mcp`.

Opaque OAuth access tokens (`oat_…`) are checked against the Context7 API before each request is served (one check per token per minute on each replica; the cache is in memory, and a rejected token stays rejected for ten minutes). An expired or revoked token gets an HTTP 401 with a `WWW-Authenticate` challenge so MCP clients refresh it. Set `MCP_OAUTH_TOKEN_VALIDATION=off` to skip that check and forward the token unchecked.

OAuth JWT access tokens from the authorization server (`OAUTH_AUTH_SERVER_URL`) are verified locally: signature against its JWKS, issuer, a `typ` of `at+jwt`, and expiry with a minute of clock tolerance. Clerk ID tokens and session JWTs share that issuer but are not access tokens, so they are always rejected. The token's `aud` must name this server (`RESOURCE_URL` origin, `/mcp`, or `/mcp/oauth`; override with a comma-separated `MCP_OAUTH_ALLOWED_AUDIENCES`). The query string of an audience on an allowed host is ignored. `MCP_OAUTH_AUDIENCE_ENFORCEMENT` sets what a mismatch does: `observe` (default) admits a token with a missing or foreign audience; `foreign` answers HTTP 401 to a token issued for another server and still admits one with no `aud`; `required` answers 401 to both. Every mismatch is logged with the OAuth client ID, the audience and the outcome, once per token per hour on each replica.

The HTTP server is stateless — it creates a fresh server instance per request and keeps no session state. Session operations therefore have nothing to attach to: a `GET` or `DELETE` on `/mcp` is answered with `405 Method Not Allowed` rather than opening a standalone Server-Sent Events stream. Server-Sent Events are used only to stream responses to `POST` requests, and keepalive heartbeats are disabled.

Stdio transport with API key:

```bash theme={null}
node packages/mcp/dist/index.js --transport stdio --api-key YOUR_API_KEY
```

## Environment Variables

You can use the `CONTEXT7_API_KEY` environment variable instead of passing the `--api-key` flag. This is useful for:

* Storing API keys securely in `.env` files
* Integration with MCP server setups that use dotenv
* Tools that prefer environment variable configuration

> [!WARNING]
>
> The `--api-key` CLI flag takes precedence over the environment variable when both are provided.

### Using .env File

```bash theme={null}
# .env
CONTEXT7_API_KEY=your_api_key_here
```

### MCP Configuration with Environment Variable

```json theme={null}
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

## Local Development Configuration

When developing locally, use this configuration to run from source:

```json theme={null}
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/folder/context7/packages/mcp/src/index.ts",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}
```

## Testing with MCP Inspector

Test your setup using the MCP Inspector:

```bash theme={null}
npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp
```

This opens an interactive inspector to verify Context7 tools are working correctly.


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