Use Inkitt MCP from your coding CLI

This guide shows you how to connect Inkitt's MCP server to the three major coding CLIs — Claude Code, Codex CLI, and Gemini CLI — using a Personal Access Token (PAT) that you can create from your Settings > MCP Server tab.

If you're using Claude.ai, ChatGPT.com, or Gemini on the web, this guide doesn't apply — those clients use OAuth-only for installation, and this is not currently supported.

Before you start

You'll need:

An Inkitt Personal Access Token (PAT). Generate one at here.
The Inkitt MCP server URL: https://mcp-server.inkitt.com/mcp
Node.js 18+ if you don't already have it.

We recommend storing your PAT in an environment variable rather than pasting it into config files or shell history. The examples below use INKITT_PAT consistently — set it once in your shell:

export INKITT_PAT="your-pat-here"

For persistence, add the export to ~/.zshrc, ~/.bashrc, or your secrets manager of choice (1Password CLI, direnv, etc.). Never commit a literal PAT to version control.

Supported CLIs:

Claude Code
Codex CLI
Gemini CLI

Claude Code

Claude Code stores MCP config either in user settings or in a project-level .mcp.json you can share with your team.

Quick add (user-scope, just you, all projects):

claude mcp add --transport http --scope user inkitt \
  https://mcp-server.inkitt.com/mcp \
  --header "Authorization: Bearer ${INKITT_PAT}"

Project-scoped (.mcp.json at project root, shareable via git):

{
  "mcpServers": {
    "inkitt": {
      "type": "http",
      "url": "https://mcp-server.inkitt.com/mcp",
      "headers": {
        "Authorization": "Bearer ${INKITT_PAT}"
      }
    }
  }
}

Claude Code expands ${VAR} from your environment at connect time, so this file is safe to commit as long as INKITT_PAT lives outside the repo.

Verify:

claude mcp list
# In a Claude Code session:
/mcp

You should see inkitt listed with its tools.

Codex CLI

Codex stores MCP config in TOML at ~/.codex/config.toml (user-scope) or .codex/config.toml in a trusted project directory. The CLI and the IDE extension share this config.

Quick add:

codex mcp add inkitt \
  --url https://mcp-server.inkitt.com/mcp \
  --bearer-token-env-var INKITT_PAT

The TOML this produces:

[mcp_servers.inkitt]
url = "https://mcp-server.inkitt.com/mcp"
bearer_token_env_var = "INKITT_PAT"

Note the design difference: Codex points at an environment variable name (INKITT_PAT), reads the value at connect time, and never stores the token literal in config. There's no equivalent of pasting Authorization: Bearer xxx into the file directly — by design.

If you need additional static headers alongside the bearer token, add them to the same section:

[mcp_servers.inkitt]
url = "https://mcp-server.inkitt.com/mcp"
bearer_token_env_var = "INKITT_PAT"
http_headers = { "X-Inkitt-Client" = "codex" }

Verify:

codex mcp get inkitt
# In a Codex session:
/mcp

Gemini CLI

Gemini stores MCP config in JSON at ~/.gemini/settings.json (user-scope) or .gemini/settings.json (project-scope, default). Note the inverted default vs. Claude Code, which scopes locally by default.

Quick add (user-scope):

gemini mcp add --transport http -s user inkitt \
  https://mcp-server.inkitt.com/mcp \
  --header "Authorization: Bearer ${INKITT_PAT}"

The JSON this produces:

{
  "mcpServers": {
    "inkitt": {
      "httpUrl": "https://mcp-server.inkitt.com/mcp",
      "headers": {
        "Authorization": "Bearer ${INKITT_PAT}"
      }
    }
  }
}

Two field-name gotchas worth knowing:

The HTTP URL field is httpUrl, not url. (Gemini uses url for SSE transport — different from Claude Code and Codex, which use url for both.) Copying a JSON snippet from a Claude Code doc and editing the URL in place will fail silently.
Gemini auto-redacts environment variables matching TOKEN*, SECRET*, KEY*, AUTH*, CREDENTIAL* from any stdio MCP server it spawns. This doesn't affect HTTP headers (your ${INKITT_PAT} expansion will work fine), but if you're using a stdio bridge like mcp-remote, you'll need to explicitly list INKITT_PAT in the server's env property.

Verify:

# In a Gemini session:
/mcp

How to use the MCP after it's installed

Once the server is connected, you can talk to your CLI in plain English — it'll figure out which Inkitt tools to call. The full toolset covers reading, drafting, editing, organizing, and publishing stories and chapters. Here are starter prompts grouped by what you're trying to do.

Get oriented (read-only — safe to start here):

What stories do I have on Inkitt?
Show me the details and chapter list for "[story title]".
What's the current cover image for "[story title]"?
What story types, age ratings, and languages does Inkitt support?

Draft and create:

Create a new draft story on Inkitt called "[story title]" with this summary: [paste summary]. Set the genre to romance and age rating to 18+.
Add a new chapter to "[story title]" called "[chapter title]" with this content: [paste draft, or reference a local file].
I'm going to paste my chapter draft below. Create it as the next chapter in "[story title]" and keep it as a draft, don't publish yet.

Edit and refine:

Pull up chapter 3 of "[story title]" and suggest line-edits for pacing in the second half. (Read-only — your CLI will fetch the chapter and respond with edits in chat. Follow up with "now apply those edits" if you want the MCP to write them back.)
Update the summary of "[story title]" to: [new summary].
Read all chapters of "[story title]" and tell me where the timeline gets confusing.

Manage publication state:

What's the publish status of each chapter in "[story title]"?
Publish the next unpublished chapter of "[story title]".
Unpublish chapters 5 through 8 of "[story title]" — I need to do a structural revision.
Reorder the chapters of "[story title]" so the prologue comes after chapter 2.

Prompt patterns that work well

Reference stories by title in quotes. The CLI will resolve them via the list/get tools. If you have multiple stories with similar titles, include enough context to disambiguate, or paste the story ID.
Chain operations in a single prompt. "Create a new chapter from this draft, then show me the full chapter list so I can confirm the order looks right." The CLI will plan the multi-step call sequence and you'll get a single coherent reply.
Use the MCP as a reading layer, not just a writing layer. Most of the leverage is in pulling existing content into the CLI so the model can reason over it — "compare the voice in chapter 2 vs chapter 8" is a much better prompt than asking the model to guess from memory.
Be explicit about destructive operations. Delete and unpublish-all tools exist; CLIs will ask for confirmation, but it's still worth saying "only delete if I confirm" in your prompt to slow things down.
Stay in draft until you mean it. New chapters default to draft status. Publishing is a separate, explicit step — useful when you want to iterate with the model on multiple chapters before going live.

Troubleshooting

Tools don't show up after adding the server.

Run the CLI's mcp list (or in-session /mcp) command to check connection status. The most common causes:

INKITT_PAT isn't set in the shell that launched the CLI. Run echo $INKITT_PAT to confirm.
PAT is expired or revoked. Generate a new one at your Inkitt token settings page.
(Gemini only) You used url instead of httpUrl in settings.json. Gemini silently falls back to SSE and the connection hangs.

401 Unauthorized on every tool call.

The header isn't being attached. Check that your config uses the exact form shown above — for Claude Code and Gemini, the header value must include the literal word Bearer followed by a space, then the token.

403 Forbidden after a successful connection.

Your PAT was accepted but doesn't have the scope for the tool you're calling. Check your PAT's permissions in Inkitt's token UI.

The token shows up in shell history.

Use the env-var pattern (${INKITT_PAT} in config files), or for one-off CLI invocations, prefix the command with a space — most shells with HISTCONTROL=ignorespace will skip the line.

Use Inkitt MCP from your coding CLI

Before you start

Claude Code

Codex CLI

Gemini CLI

How to use the MCP after it's installed

Prompt patterns that work well

Troubleshooting

Related articles