---
title: Client Setup
description: Configure AI Workflow MCP in Claude Code and HTTP MCP clients.
type: guide
summary: Client configuration, environment variables, and smoke tests.
related:
  - /en/docs/quickstart
  - /en/docs/api-keys
  - /en/docs/mcp
---

# Client Setup



AI Workflow MCP uses Streamable HTTP MCP at:

```txt
https://mcp.aiworkflowmcp.com/mcp
```

Use the same endpoint in every client. Add an API key when the client supports headers.

## Environment Variable [#environment-variable]

Store the key outside the config file when possible:

```bash
export AIWORKFLOWMCP_API_KEY="ak_..."
```

Never commit real keys into a repository.

## Claude Code [#claude-code]

```bash
claude mcp add --transport http aiworkflowmcp https://mcp.aiworkflowmcp.com/mcp
```

If your Claude Code version supports request headers for HTTP MCP servers, add:

```txt
Authorization: Bearer ${AIWORKFLOWMCP_API_KEY}
```

If headers are not supported in your current client build, public calls still work. Use REST with the bearer header for authenticated smoke tests until the client supports it.

## Cursor [#cursor]

Add an HTTP MCP server entry:

```json
{
  "mcpServers": {
    "aiworkflowmcp": {
      "url": "https://mcp.aiworkflowmcp.com/mcp",
      "headers": {
        "Authorization": "Bearer ${AIWORKFLOWMCP_API_KEY}"
      }
    }
  }
}
```

Restart the editor after changing MCP configuration.

## Cline [#cline]

Use the same HTTP server shape:

```json
{
  "mcpServers": {
    "aiworkflowmcp": {
      "url": "https://mcp.aiworkflowmcp.com/mcp",
      "headers": {
        "Authorization": "Bearer ${AIWORKFLOWMCP_API_KEY}"
      }
    }
  }
}
```

Then ask the agent to list available tools. A healthy client should show `get_ai_model`, `get_coding_tool`, `search_official_docs`, `search_skills`, `search_cli`, `search_mcp`, `search_frameworks`, `route_framework`, and `get_framework`.

## Windsurf, Codex, OpenCode, And Generic Clients [#windsurf-codex-opencode-and-generic-clients]

Use the generic MCP configuration if the client supports Streamable HTTP:

```json
{
  "name": "aiworkflowmcp",
  "transport": {
    "type": "http",
    "url": "https://mcp.aiworkflowmcp.com/mcp",
    "headers": {
      "Authorization": "Bearer ${AIWORKFLOWMCP_API_KEY}"
    }
  }
}
```

If the client expects a simpler object, keep only:

```json
{
  "url": "https://mcp.aiworkflowmcp.com/mcp",
  "headers": {
    "Authorization": "Bearer ${AIWORKFLOWMCP_API_KEY}"
  }
}
```

## Verify The Connection [#verify-the-connection]

Use `tools/list` first because it does not require tool arguments:

```bash
curl -fsS https://mcp.aiworkflowmcp.com/mcp \
  -H "content-type: application/json" \
  -H "Authorization: Bearer ${AIWORKFLOWMCP_API_KEY}" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

Then call a deterministic read tool:

```bash
curl -fsS https://mcp.aiworkflowmcp.com/mcp \
  -H "content-type: application/json" \
  -H "Authorization: Bearer ${AIWORKFLOWMCP_API_KEY}" \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_official_docs",
      "arguments": {
        "query": "Claude Code MCP HTTP configuration",
        "fresh_only": true,
        "limit": 3
      }
    }
  }'
```

## Agent Prompt Contract [#agent-prompt-contract]

Tell the agent:

```txt
Use AI Workflow MCP before answering current AI coding tool, model, MCP server, or agent framework questions. Query in concise English. Prefer fresh_only=true for source-sensitive answers. Cite evidence.source_url when making product or pricing claims.
```

## Common Setup Mistakes [#common-setup-mistakes]

* Using `/v1/...` as the MCP URL. MCP clients must use `/mcp`.
* Sending a key without the `Bearer` prefix.
* Passing an empty argument such as `model_id: ""`.
* Expecting localized tool names. Tool names and JSON fields stay English.
* Treating public unauthenticated access as production quota. Use an API key for real workflows.


---

For a semantic overview of all documentation, see [/en/sitemap.md](/en/sitemap.md)

For an index of all available documentation, see [/en/llms.txt](/en/llms.txt)