“Claude Code review” can mean two things: the review features built into Claude Code, or how you review the code Claude Code writes. This post covers both. First the four built-in options and what each one is for, checked against Anthropic’s documentation in October 2026. Then the rules I follow, which came from things that went wrong.

The four built-in options

Two related commands are worth knowing. /security-review checks the diff between your branch and the default branch on origin for security problems such as injection, auth issues and data exposure. /simplify looks for cleanup only: reuse, simplification, efficiency, and whether the change sits at the right level of abstraction. The docs are explicit that /simplify does not look for correctness bugs. If you want bugs found, use /code-review.

1. /code-review, in your terminal

/code-review

With no target, it reviews your branch’s commits ahead of its upstream plus any uncommitted changes. You can also pass a PR number, a branch, a path or a range such as main...my-feature. /review is an alias.

The parts that matter in practice:

• Effort levels. /code-review low through /code-review max. At low and medium it reports only the findings it is most sure of, so you see fewer false alarms. high to max cover more ground and may include findings it is less sure of. If you do not type a level, it reuses the last one you typed, even from an earlier session.
• It runs in the background as a subagent with its own context window, so it does not fill up the conversation you are working in.
• --fix applies the findings to your working tree. When the review runs in the background (the default), those edits happen outside your session’s checkpoints, so /rewind will not undo them. Commit before you run it, and use git to back out.
• --comment posts the findings on a GitHub pull request as inline comments.
• It follows your CLAUDE.md. It does not read REVIEW.md (more on that below). If you want a local review to enforce a rule, the rule has to be in CLAUDE.md.

This is the one to run on every change before you commit. It needs no setup and no GitHub App.

2. Ultrareview, in the cloud

/code-review ultra
/code-review ultra 1234

Ultrareview sends the review to a cloud sandbox where a larger group of reviewer agents works on it in parallel. Anthropic’s docs say every finding it reports is independently reproduced and verified, which is the main difference from a local review. It reviews your branch against the default branch, or a GitHub PR if you pass its number. Your terminal stays free while it runs.

Limits worth knowing before you plan around it:

• It needs a claude.ai sign-in. It does not run on Amazon Bedrock, Google Cloud’s Agent Platform or Microsoft Foundry, or for organisations with Zero Data Retention.
• It is a research preview. Pro and Max accounts get three free runs, once. After that it uses paid usage credits.
• Claude never starts it on its own. You have to type it.
• For CI, there is a claude ultrareview subcommand that waits for the findings and prints them.

Use it for the changes where a missed bug is expensive: billing, auth, migrations, anything that deletes data.

3. Code Review, the managed GitHub service

This one is for teams. An organisation Owner installs the Claude GitHub App and picks which repositories to review. From then on, reviews start when a PR opens, on every push, or only when someone comments @claude review, depending on the setting for each repository.

Several agents look at the diff and the code around it, a verification step filters out false positives, and the results arrive as inline comments tagged by severity:

• Important: a bug that should be fixed before merging.
• Nit: worth fixing, not blocking.
• Pre-existing: a real bug that this PR did not introduce.

It never approves or blocks a PR. The check run always finishes as neutral, so if you want findings to block a merge, you read them in your own CI. Anthropic’s docs put the average review at about 20 minutes and $15 to $25 in usage, billed separately from plan usage (October 2026). Reviewing on every push multiplies that by the number of pushes, so manual mode with @claude review on the PRs that matter is the cheaper setting.

4. Claude Code GitHub Actions

If you want Claude in your own CI instead of Anthropic’s service, run /install-github-app inside Claude Code. It installs the GitHub App, stores your key as a repository secret, and pushes a branch with the workflow file. GitHub then opens with a pull request ready for you to create. Merge it, and you can mention @claude in a PR or issue to get a review or a change. This gives you the most control and the most setup.

CLAUDE.md or REVIEW.md

The managed Code Review reads two files from your repository:

• CLAUDE.md is general project guidance. Code Review treats a new violation of it as a Nit, and it also flags a PR that makes a statement in CLAUDE.md out of date.
• REVIEW.md is only for review. It goes straight to the agents that find and verify issues, so rules there land more reliably than the same rules in a long CLAUDE.md.

Remember the catch from earlier: the local /code-review reads CLAUDE.md and not REVIEW.md. If you use both, rules that must apply everywhere go in CLAUDE.md.

Here is the kind of REVIEW.md I would write for a Laravel and Inertia app. Most of the rules come from the instructions I keep for my own Laravel projects:

# Review instructions

## What Important means here
Important = breaks production behaviour, leaks data, or cannot be rolled
back. Style and naming are Nit at most. Report at most five Nits.

## Always check
- Index, unique and foreign key names stay under 64 characters. SQLite
  ignores the limit locally; MySQL rejects the migration in production.
- Controllers called by Inertia forms return a redirect, never
  response()->json().
- Every query that reads customer data is scoped to the current team.
- A test's assertions match its name. Read the assertion, not the title.

## Do not report
- Anything CI already enforces: formatting, lint, type errors.
- Generated files and lockfiles.

Keep it short. The docs warn that a long REVIEW.md dilutes the rules that matter most.

How I review code an agent wrote

The tools above find bugs in code. They do not decide what ships. These are the rules I follow for that part.

Run the gate before any review

Build, type check, tests. Do this before asking any reviewer, human or agent, to read the diff. A review of code that does not compile wastes everyone’s time, and a model will happily review it anyway.

Do not let the author approve its own work

The session that wrote the code already believes it is right. In my experience, it is more likely to say its own diff looks fine. So the review should come from somewhere else. When I run an implementation plan, a fresh reviewer agent, with its own context, checks each task before the next one starts. A different model, such as Codex, goes one step further: different training, different blind spots. I compared the two in Claude Code vs Codex.

Reproduce every finding before you act on it

A finding is a claim, not a fact. Before I change code because a reviewer said so, I run the case that is supposed to fail. Some findings are real. Some describe code paths that cannot happen.

The same rule applies to a reviewer saying a failure is “pre-existing”. Prove it: run the same test on the commit before the change. If you cannot show it failing there, it belongs to this change.

Read what a test asserts, not what it is called

This one hurt. On Schedule & Chill, a test named “hands the real user model to the tools” passed for the whole time the feature it described was broken. It checked a different way of getting the user from the one the code actually used, so it could not fail. The name said one thing and the assertion tested another. The details are in my Laravel MCP post.

When an agent writes both the code and the test, the test was written by something that already believed the code was right. Read the assertion line.

Separate “can hurt money or customers” from everything else

I sort each finding into two groups before fixing anything:

1. Blocks the merge. Wrong data, lost data, a broken payment, a security hole, a user who cannot finish what they came to do.
2. Follow-up. Naming, structure, a cleaner way to write it.

Group 1 gets fixed now. Group 2 gets fixed if it is cheap, or written down if it is not. Without this split, a review turns into twenty equal-looking comments and the one that matters gets lost.

Check facts by hand

Code reviewers check code. They do not check whether a sentence on your site is still true. A free tool page on JuggleHire told users to “export the scorecard as a PDF”. The tool only offered copy and a .txt download. On a pricing comparison page, five of eleven competitor prices had changed since the page was written. Neither is a code problem, so a code review would not catch either.

Prices, limits, feature claims and tutorial steps get checked against the real source before they ship: the live pricing page, the real tool, the current docs.

Let a human own the merge

On my own products, I am that human. On a shared codebase where another engineer reviews my PRs, the agent does the first pass and the human decides. An agent never approves and never merges there. Having access to the repo is not the same as having approval.

Which one to use

• Every change, before you commit: /code-review at medium, after your build and tests pass.
• A change that touches money, auth or data: add /security-review and, if you have access, /code-review ultra.
• A team that already reviews on GitHub: the managed Code Review in manual mode, with a short REVIEW.md.
• You want it in your own CI: GitHub Actions through /install-github-app.

And whichever you pick, the last reviewer is you. The built-in reviewers are good at “does this code do what it says”. Checking that what it says is true is still your job.

• Schedule & Chill, a social media scheduler. Its MCP server is public: 22 tools, reachable with an API token or over OAuth 2.1.
• ShipTell, a support and changelog tool. Its server covers changelogs, the inbox, the knowledge base and the roadmap.
• JuggleHire, a hiring platform. A small internal server, read-only, that my own agents use to look up customers.

The package makes the first version easy. This post covers that part quickly, then spends most of its time on six problems I had to fix after the first version worked. They are not in the docs, and most of them are not bugs in the package. They come from running a Laravel app for a caller that is a model, not a person.

One warning first: laravel/mcp changes fast. It reached 1.0 in September 2026. My servers still run 0.6 and 0.9. The API changed between those two, and it changed again in 1.0. The code below follows the current Laravel docs. Check the docs for your version before copying anything.

The setup in four commands

composer require laravel/mcp
php artisan vendor:publish --tag=ai-routes
php artisan make:mcp-server SocialServer
php artisan make:mcp-tool GetAccounts

The second command creates routes/ai.php. That is where servers are registered, and there are two ways to do it:

// routes/ai.php
use App\Mcp\Servers\SocialServer;
use Laravel\Mcp\Facades\Mcp;

// Over HTTP, for remote clients. Protected like any other route.
Mcp::web('/mcp', SocialServer::class)
    ->middleware(['auth:sanctum', 'throttle:mcp']);

// As an Artisan command (stdio), for a client on your own machine.
Mcp::local('social', SocialServer::class);

throttle:mcp needs a rate limiter called mcp. Define it in a service provider with RateLimiter::for('mcp', ...), like any other named limiter.

A tool, written for a model

Here is a tool in the shape I use most. It lists the accounts a user can post to, so the model fetches real IDs instead of making them up:

<?php

namespace App\Mcp\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Tool;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;

#[Name('get_accounts')]
#[Description('List the social accounts this user can post to. Call this before scheduling anything, and use only the ids it returns.')]
#[IsReadOnly]
class GetAccounts extends Tool
{
    public function schema(JsonSchema $schema): array
    {
        return [];
    }

    public function handle(Request $request): Response
    {
        $accounts = $request->user()->socialAccounts()->get();

        return Response::structured([
            'count' => $accounts->count(),
            'accounts' => $accounts->map(fn ($account) => [
                'id' => $account->id,
                'platform' => $account->platform,
                'name' => $account->account_name,
                'health' => $account->needsReconnect() ? 'needs_reconnect' : 'ok',
            ])->all(),
        ]);
    }
}

Three details in there matter more than they look:

1. The description tells the model what to do next. “Call this before scheduling anything” is an instruction. The description is the main prompt text you control in a tool, so use it.
2. health, not is_active. On Schedule & Chill, is_active stayed true for an account whose refresh token had died. Anything that trusted it, a model included, would schedule posts into a channel that could not publish. Give the model the field you would check yourself.
3. #[IsReadOnly] tells the client the tool changes nothing. It is a hint, not a guarantee, but it costs one line.

Register the tool in the server’s $tools array. The server class also takes an #[Instructions('...')] attribute. Mine says which tool to call first and which actions cannot be undone. The client receives it when it connects.

What I had to fix

1. It worked locally and returned 404 in production

This one cost me several hours on JuggleHire.

The MCP server worked on my machine. In production, every request returned 404. The route did not exist.

The cause was composer.json. I had never required laravel/mcp myself. It was installed only because Laravel Boost, a dev dependency, pulled it in. Production installs with composer install --no-dev, so the package was not there, its service provider never booted, and routes/ai.php was never loaded.

The fix was one line, composer require laravel/mcp. The lesson is wider:

• Run composer why laravel/mcp. If the only answer is a require-dev package, production will not have it.
• A 404 means the route is not registered. A 401 means it is. Hit the endpoint without a token. If you get 404, stop debugging auth.

2. Local and web are two different servers in practice

Mcp::local and Mcp::web can point at the same class, but they do not run in the same place. The local one is an Artisan command on your machine, so it reads your local .env and your local database. The web one runs on your server against production.

On JuggleHire that meant the local server answered with seed data while the production endpoint was broken, and “it works for me” was true and meaningless at the same time. Test the transport your users will use. If you keep both, name them so nobody confuses them.

3. MCP routes in routes/web.php need a CSRF exception

The package loads routes/ai.php without the web middleware group, so there is no CSRF check on those routes. On Schedule & Chill the MCP routes live in routes/web.php instead. That puts them inside the web group, and a POST from an AI client carries no CSRF token, so without an exception Laravel rejects it with a 419.

If your MCP routes live in routes/web.php, exclude them:

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->validateCsrfTokens(except: [
        'mcp',
        'mcp-oauth',
        'oauth/register', // dynamic client registration, from Mcp::oauthRoutes()
    ]);
})

Or keep them in routes/ai.php, which is what it is for.

4. With OAuth, the tools saw a different user than the middleware

Schedule & Chill serves the same server twice. /mcp takes a Sanctum token that people paste into a config file. /mcp-oauth uses Passport, so that claude.ai, Claude Desktop and other clients can offer a “Connect” button. The Laravel docs recommend Passport for exactly this reason: OAuth 2.1 is what the MCP spec documents. Mcp::oauthRoutes() registers the discovery documents and client registration routes the clients probe for.

On that OAuth path, my setup needed a middleware that swapped the identity model Passport resolved for the real User. It called $request->setUserResolver(), and the test for it passed.

Every tool call still failed. In laravel/mcp, Request::user() resolves the user through the auth manager, not through the HTTP request. The api guard still held the old identity model, so the first relation call died. The fix was to also call Auth::guard('api')->setUser($user).

The test passed because it asserted request()->user(), which the tools never call. Two rules came out of it:

• When a framework has two ways to get the current user, test the one the caller actually uses.
• A successful handshake proves nothing. initialize returned 200, the consent screen rendered, tokens were issued. Only a real tool call that touches a relation shows whether anything behind the door works.

5. The 401 had no WWW-Authenticate header

The MCP authorization spec gives a server two ways to point a client to its OAuth metadata: a WWW-Authenticate header on the 401, or a well-known URL the client has to try on its own. Clients read the header first. Without it, they have to guess, and some just report that the server does not support OAuth.

Mcp::web() adds a middleware for that header, AddWwwAuthenticateHeader. But Laravel’s middleware priority list runs authentication earlier, so the 401 was rendered before that middleware could add the header. Clients got a bare 401.

laravel/mcp 1.0 fixes this inside the package. On 0.9 and earlier, move the middleware ahead of authentication yourself:

use Illuminate\Contracts\Auth\Middleware\AuthenticatesRequests;
use Laravel\Mcp\Server\Middleware\AddWwwAuthenticateHeader;

$middleware->prependToPriorityList(
    before: AuthenticatesRequests::class,
    prepend: AddWwwAuthenticateHeader::class,
);

Use the AuthenticatesRequests interface as the anchor, not the Authenticate class. The priority list holds the interface. Naming the class matches nothing, and the middleware is quietly added to the end of the list, which looks like the fix and changes nothing. Check with curl -i that the header is really there.

6. A capped list looked like the whole list

JuggleHire’s internal server has a tool that lists customers. It returned at most 50 rows and did not say so, and production has far more customers than that. An agent that counted the rows got 50, and nothing in the response told it the real number was much higher. I ended up writing a warning into my own notes: never quote that number as a total. The fix belongs in the tool, not in my notes.

A model cannot know a list was cut unless you tell it. Any tool that limits results should return the total and say the list is partial:

return Response::structured([
    'total' => $total,
    'returned' => $customers->count(),
    'truncated' => $total > $customers->count(),
    'customers' => $customers->all(),
]);

The same rule applies to anything the server decides for the model. On Schedule & Chill, scheduling tools return the time we understood in UTC, in local time and with the timezone name, so an agent can check our reading of its input. It cannot look at a calendar to confirm.

Errors are instructions

The Laravel docs say it directly: on validation failure, AI clients act on the error messages you give them. So write messages a model can act on:

$request->validate([
    'scheduled_at' => ['required', 'date', 'after:now'],
], [
    'scheduled_at.after' => 'scheduled_at must be in the future. Send an ISO-8601 time after the current time, with a timezone offset.',
]);

On Schedule & Chill, the tools that act on posts and uploads return errors as a JSON object with code, problem, cause and fix. The fix field is the one that matters. A model that reads it can correct itself without asking the human.

One more thing about errors: the error path must never throw. Error messages often include outside text, such as an account name or a platform’s error body. On Schedule & Chill one invalid UTF-8 byte in that text made json_encode throw, and the whole tool call failed instead of returning the error. Clean outside strings before you encode them.

Testing it

The package has two built-in ways to test, and both are worth using.

Unit tests call a tool directly on the server class:

it('lists the user\'s accounts', function () {
    $user = User::factory()->create();
    SocialAccount::factory()->for($user)->create(['account_name' => 'Acme on LinkedIn']);

    SocialServer::actingAs($user)
        ->tool(GetAccounts::class)
        ->assertOk()
        ->assertSee('Acme on LinkedIn');
});

The MCP Inspector connects to a running server so you can call tools by hand: php artisan mcp:inspector mcp for the web server at /mcp, or php artisan mcp:inspector social for the local one.

Then do the test that finds the real problems. Connect an actual client and give it a plain-language task that needs three or four tool calls, without naming the tools. In Claude Code:

claude mcp add --transport http social https://your-app.test/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Watch which tool it calls first, which argument it guesses, and which description sends it the wrong way. That found more problems in my servers than all the schema work did.

Who this is not for

If your code decides which endpoint to call and the model only writes text, you do not need an MCP server. A normal API call is simpler. I wrote about where that line sits in MCP vs API. For the framework-neutral version of this post, with the TypeScript SDK and the mistakes every MCP server makes, see how to build an MCP server.

If you are already on Laravel and your users work in Claude, Cursor or another MCP client, the package is the shortest path I know. You are not building a second app. You are exposing the one you have, with its policies, validation and services intact. The work is in what this post covers: making it behave when the caller is a model.

I have run both Claude Code and OpenAI’s Codex CLI daily for about six months across Laravel, Inertia/React and TypeScript codebases. This is what I actually found, including the parts where the tool I use more lost.

The short version

If you only take one thing: they are not really competing for the same job. I stopped choosing between them around month three and started using both, which I explain at the end.

Be careful with the benchmark numbers

Search for this comparison and you will find SWE-bench Verified scores quoted to one decimal place, usually both above 96%. I am not going to repeat those as if I verified them, because I did not, and neither did most of the posts quoting them.

Two things are worth knowing about that:

1. The gap between the top agents on those benchmarks is now smaller than the gap between a good prompt and a lazy one. When two tools are within a point of each other, the benchmark has stopped being the deciding factor for your work.
2. Benchmarks measure “did the test pass”, not “would you merge this”. Those are different questions, and the second one is the one that costs me time.

So the rest of this is what I observed, framed as observation rather than measurement. Where I say “faster” or “cheaper” I mean in my work, on my codebases, which is a sample of one.

Where Claude Code wins for me

Multi-file work where the plan matters more than the code. The thing I do most is change a feature that touches a controller, a React page, a migration, a config file and three tests. Claude Code holds that shape in its head. It reads the surrounding code and matches it — my naming, my comment density, the way I structure a Laravel domain folder — rather than writing generically correct code that reads like it came from somewhere else.

It tells you when it disagrees. More than once it has stopped and said the approach I asked for would break something else, and it was right. That is worth real money when nobody else is reviewing your work.

Skills, subagents and hooks. This is the part that changed how I work, not just how fast I type. I keep a set of skill files that encode things I have learned the hard way — how my deploy pipeline works, which database gotchas bite me when SQLite passes locally and MySQL fails in production, what my commit messages should look like. Claude Code loads the relevant one on its own. Codex has no real equivalent that I have found.

Worktrees. I often run several sessions on the same repository. Claude Code handles git worktrees well enough that I can genuinely parallelise, which was not true six months ago.

Where Codex wins for me

It uses far fewer tokens for the same result. This is the difference I feel most in the bill. On a bounded task — “add validation to this endpoint and update the test” — Codex gets there with a fraction of the back-and-forth. Claude Code will read more files than it strictly needed to.

Review is its best mode. This surprised me. Handing Codex a diff and asking what is wrong with it produces tighter, less agreeable feedback than asking Claude Code the same thing. Claude Code is more likely to tell me the diff looks good. Codex is more likely to find the thing I missed.

Sandboxed autonomy. When I genuinely do not want to watch — a mechanical refactor across forty files, a dependency bump — letting it run and reviewing at the end is the right shape, and Codex is built for that shape.

Where both of them still fail

Neither tool checks whether what it wrote is true.

This is the failure that has cost me the most. A tool page on one of my products had a step in its instructions saying “export the result as a PDF”. There was no PDF export. The code offered clipboard copy and a .txt download, and the prose next to it had been confidently wrong for months. Both agents had read that page. Neither flagged it, because prose that contradicts the component beside it is not a syntax error.

The same class of thing bit me on competitor pricing: five of eleven prices on a comparison page had drifted since they were written, and no amount of code review catches a number that is simply out of date.

So the rule I ended up with: agents are good at “does this run” and bad at “is this still true”. Anything factual — a price, a limit, a capability claim, a step in a tutorial — gets verified by me against the actual thing, every time. I now write tests that fail when a claim goes stale, which is the only version of this that survives me forgetting.

The second shared failure is over-building. Ask for a fix, get a fix plus a refactor plus three new tests plus a README section nobody asked for. Claude Code does this more than Codex does. The prompt that works is boring and specific: say what to change, say what not to touch.

What I actually do now

I stopped picking one:

1. Claude Code writes the feature. It gets the multi-file work, the planning, and anything where matching the existing codebase matters.
2. Codex reviews the diff before it merges. Different model, different training, genuinely different opinions — it catches things the author missed, in a way that asking the author to re-read its own work does not. The full routine, including Claude Code’s own review commands, is in Claude Code review.
3. I verify every factual claim myself. Prices, limits, capabilities, tutorial steps. Neither agent does this and both will state a wrong thing confidently.

That third step is not optional and it is the one people skip.

Which should you pick, if you can only pick one

• Building something new, or working alone with nobody reviewing you — Claude Code. The steerability and the skills system compound over months in a way that raw speed does not.
• Working in a team with review already in place, or cost-sensitive — Codex. You already have humans catching mistakes; you want throughput, and it is cheaper per task.
• Mostly reviewing rather than writing — Codex, without much hesitation.

And if the honest answer is that you have not tried either seriously for more than a week: pick either one and use it on real work for a month. The difference between the two is much smaller than the difference between using one properly and using it as autocomplete.

I build software products solo under Lomeyo, LLC — a hiring platform, a social scheduler, and a few smaller things. Everything above comes out of that work. Three of them have MCP servers built in Laravel, and here is what building those taught me.

This covers both, then builds a small bot that actually runs.

Getting the key

1. Go to console.x.ai. This is the developer console, and it is separate from the Grok consumer app — you do not need an X Premium subscription to use the API.
2. Sign up or sign in. There is a short onboarding asking what you are building and asking you to accept the terms.
3. Open API Keys in the sidebar, then Create API Key.
4. Copy it immediately. Like most providers, the full key is shown once.

That is the whole flow. If you are being asked to pay for X Premium, you are in the consumer product, not the developer console.

Before you write any code, check two things in the console

• Your credit balance and what it is. xAI runs promotional credits for new accounts, and has at times offered additional monthly credits in exchange for opting into a data-sharing programme. Both the amounts and the terms have changed more than once — read what your own console says rather than trusting any blog post, including this one. There is no permanent free tier; after credits, it is pay per token.
• Whether the data-sharing option is on. If extra credits are attached to sharing your API traffic for training, that is a real trade. For a hobby bot it is probably fine. For anything touching customer data it is a decision you should make deliberately, not one you should discover later.

Store it properly

The single most common mistake with a fresh API key is committing it.

# .env  — and make sure .env is in .gitignore
XAI_API_KEY=xai-...

If you have already pushed one to a public repository, rotate it in the console rather than deleting the commit. Scrapers find keys in public git history within minutes, and the commit is not the only copy.

The useful part: it speaks OpenAI

The thing that makes the Grok API quick to adopt is that it is OpenAI-compatible. You do not need a new SDK. You point the OpenAI client at a different base URL:

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

response = client.chat.completions.create(
    model="grok-4",
    messages=[
        {"role": "system", "content": "You are terse. Answer in one sentence."},
        {"role": "user", "content": "Why is the sky blue?"},
    ],
)

print(response.choices[0].message.content)

Node is the same idea:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const res = await client.chat.completions.create({
  model: "grok-4",
  messages: [{ role: "user", content: "Give me one fact about Bangladesh." }],
});

console.log(res.choices[0].message.content);

Two caveats on that compatibility:

• Model names are xAI’s, not OpenAI’s. Check the console or the models endpoint for what is currently available rather than guessing a version string. Model IDs change.
• Compatible does not mean identical. The common path — chat completions, streaming, tool calling — works. Provider-specific extras on either side do not always map. If something behaves oddly, that seam is the first place to look.

Building a bot

The most common thing people want a Grok key for is a bot. Here is a Telegram one that works, in about forty lines.

import os
import httpx
from openai import OpenAI

XAI = OpenAI(api_key=os.environ["XAI_API_KEY"], base_url="https://api.x.ai/v1")
TG = f"https://api.telegram.org/bot{os.environ['TELEGRAM_TOKEN']}"

SYSTEM = "You are a helpful assistant in a group chat. Keep replies under 60 words."

def reply(chat_id: int, text: str) -> None:
    httpx.post(f"{TG}/sendMessage", json={"chat_id": chat_id, "text": text})

def answer(prompt: str) -> str:
    res = XAI.chat.completions.create(
        model="grok-4",
        messages=[
            {"role": "system", "content": SYSTEM},
            {"role": "user", "content": prompt},
        ],
    )
    return res.choices[0].message.content

def main() -> None:
    offset = 0
    while True:
        # long-poll Telegram; 30s timeout keeps this cheap
        r = httpx.get(f"{TG}/getUpdates", params={"offset": offset, "timeout": 30}, timeout=35)
        for update in r.json().get("result", []):
            offset = update["update_id"] + 1
            message = update.get("message", {})
            text = message.get("text")
            if not text:
                continue
            reply(message["chat"]["id"], answer(text))

if __name__ == "__main__":
    main()

That is deliberately the simplest thing that works. Three changes turn it into something you would leave running:

1. Keep conversation history per chat, capped. Without it every message is context-free. With it uncapped, your token bill grows with the conversation forever — keep the last N turns, not all of them.
2. Rate limit per user. A bot in an open group is a bot anyone can spend your credits on. This is the failure mode that turns a hobby project into a bill.
3. Handle errors. Wrap the API call. A 429 or a 500 should mean “try again shortly”, not a crashed process and a silent bot.

The billing detail that catches people

You are billed per token, input and output, and input includes everything you send — the system prompt, the conversation history, and any documents you paste in. A long system prompt is not free; you pay for it on every single call.

For a bot, the practical consequences are:

• A 500-word system prompt costs you on every message, forever. Keep it short.
• Unbounded chat history is the most common source of a surprising bill.
• Set a spend alert in the console on day one, not after the first bad week.

When Grok is the right pick

Honestly: the API is quick to adopt because it is OpenAI-compatible, and its distinctive asset is real-time access to what is happening on X. If your product needs current, public conversation — a monitoring tool, a trend bot, anything where “what are people saying right now” is the question — that is a genuine differentiator.

If you need general reasoning or coding, the OpenAI-compatible base URL means you can benchmark it against alternatives by changing one line. Do that with your own prompts on your own task rather than trusting anyone’s benchmark table, including mine.

If your bot needs to take actions and not only answer, that is where tool calling and MCP come in. I wrote about when an MCP server helps and when a plain API call is better.

I write about the tools I actually ship with — see more writing, or what I am building.

Building one a model uses correctly took me considerably longer, and the gap between those two things is what this post is about. I run MCP servers on four products now. Everything below is a mistake I made and had to fix.

The ten-minute version

Every MCP server is the same three things:

1. A list of tools, each with a name, a description and a JSON schema for its arguments.
2. A handler per tool that does the work and returns a result.
3. A transport — stdio for something running on the user’s machine, HTTP for something running on yours.

Here is the smallest useful shape, in TypeScript, using v2 of the official SDK (@modelcontextprotocol/server), the stable line since July 2026:

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.registerTool(
  "list_accounts",
  {
    description:
      "List the social accounts this user can post to. Call this before scheduling anything so you use real account ids.",
    inputSchema: z.object({
      platform: z.string().optional().describe("Only accounts on this platform, e.g. linkedin"),
    }),
  },
  async ({ platform }) => {
    const accounts = await db.accounts.findMany({ where: platform ? { platform } : {} });
    return {
      content: [{ type: "text", text: JSON.stringify(accounts) }],
    };
  },
);

await server.connect(new StdioServerTransport());

The SDK turns the Zod schema into the JSON Schema the model sees, and it rejects arguments that do not match before your handler runs. Two notes from the SDK docs: over stdio, stdout is the protocol channel, so log with console.error, never console.log. And if you are still on v1 (@modelcontextprotocol/sdk), the imports and some method names differ, so follow the v1 docs rather than this snippet.

That runs. Now here is what goes wrong.

1. The model invents IDs

This was the first thing to break and it is the one I would warn everyone about.

My scheduling tool took social_account_ids. A developer using the REST version fetches the accounts once and hardcodes them. A model does not. Given a tool that wants account IDs, it will confidently supply account IDs that do not exist. The schema validates. The call either fails oddly or hits the wrong account.

The fix is a tool, not documentation. Add list_accounts — or whatever the equivalent is in your domain — and say in the description of every tool that consumes an ID that the model should call it first. Descriptions are prompt text. They are the only place you get to instruct the model.

2. Error messages written for humans

422 Unprocessable Entity is fine for a developer with docs open. To a model it is a dead end, and a model at a dead end guesses.

Compare:

// Useless to a model
{ "error": "Validation failed", "code": 422 }

// Useful
{ "error": "scheduled_at must be in the future. You sent 2026-01-01T10:00:00Z,
   which is in the past. Current time is 2026-09-09T14:22:00Z. Send a timestamp
   after that." }

The second one tells the model what to do next. Every error your MCP server returns should read like an instruction, and should include the value that was wrong and what a correct one looks like.

3. Silently dropped arguments

This one cost me a real production mistake, so it gets its own section.

Most MCP servers — mine included, at first — accept an options object and ignore keys they do not recognise. The call returns success. The feature you thought you enabled was never enabled, because you guessed the key name and the server threw it away without saying anything.

If a caller passes platform_options: { threadReply: true } and your server expects thread_reply, and you silently drop unknown keys, the post publishes with the default and reports success. Nothing in the logs says otherwise.

Fix it in two places. Reject unknown keys loudly, and ship a get_capabilities tool that returns the exact option keys each surface accepts, so the model can ask instead of guessing. Guessing is the default behaviour of every model and you cannot prompt it away.

4. Publishing is irreversible and models are not careful

Anything your server can do that cannot be undone needs a safe default.

For a scheduler that means: the natural tool is schedule_post with a future timestamp, not publish_now. The review window costs nothing and cancel undoes anything wrong. publish_now exists but it is the explicit choice, not the path of least resistance. The whole flow from the user’s side, including who holds the OAuth tokens and how to stop a bad post, is in this walkthrough of AI agents posting to social media on the Schedule & Chill blog.

Apply this generally. Ask which of your tools are irreversible, then make the reversible version the obvious one — in the tool name, in the description, and in what happens when a required field is missing.

5. Remote MCP means OAuth, and OAuth is most of the work

stdio is easy: the server runs on the user’s machine as their user, so authentication is “it already is them”.

Remote is a different product. Once your MCP server runs on your infrastructure and serves many users over HTTP, you need:

• A real OAuth flow, including the consent screen and the callback.
• Token storage and refresh, per user, that survives your deploys.
• Scoping, so a token cannot reach another tenant’s data.
• A way for the user to revoke it.

None of that is MCP-specific and all of it is required. Budget for it. If you already have OAuth for your product, you are most of the way there; if you do not, the MCP server is not the small project it looked like.

What Laravel developers should know

If you are on Laravel — I mostly am — the ecosystem got much better. The official Laravel MCP package lets you register a server as a route and define tools as classes, which means your existing authorisation, validation and service layer apply unchanged. That is the main advantage: you are not building a parallel application, you are exposing the one you have.

The trap is the same as everywhere else. Your form requests were written to return validation errors to a human looking at a form. Read them again as if a model is the reader.

I wrote the full Laravel version separately: Laravel MCP: what three production servers taught me covers the package setup and six failures that only showed up in production.

The test that actually tells you it works

Not a unit test. Connect a real client — Claude Desktop or Claude Code — and give it a task in plain language that requires three or four tool calls in sequence, without telling it which tools to use.

Watch what it calls. You will find:

• The tool it reached for first, which is rarely the one you expected.
• The argument it guessed instead of fetching.
• The description that was ambiguous enough to send it the wrong way.

That fifteen-minute exercise found more real problems in my servers than any amount of schema work. Do it before you ship, then again after every tool you add.

The short checklist

• One tool that lists the real IDs, and descriptions telling the model to call it first.
• Errors that say what to do next, with the bad value and a correct example.
• Unknown arguments rejected loudly, plus a get_capabilities tool.
• The reversible action is the obvious one; irreversible actions are explicit.
• Remote means OAuth, scoping and revocation — plan for it as its own project.
• Test by watching a real model use it cold.

More on what this protocol is and is not: MCP vs API — why an MCP server sits on top of your API rather than replacing it, and when building one is a waste of time.

That is the whole answer, and most explanations of this bury it. But it leaves the useful question open: if MCP does not replace your API, what does it actually change, and is it worth building?

The one-sentence version

An API is an interface for a developer who reads documentation. MCP is an interface for a model that cannot.

Same functions underneath. Different consumer, and the consumer is what changes the design.

What is actually different

Put the two side by side and the differences are narrow but they matter.

The row that matters most is the third one. On the HN thread about this, someone reduced the whole protocol to: tools can be added at runtime instead of at design time. That is closer to the truth than most long-form explanations, mine included.

The part that surprised me building one

I assumed an MCP server was a thin wrapper over my existing controllers. Take the endpoint, describe it in a schema, done.

That is technically true and produces a bad server.

Here is why. My scheduler’s REST API has an endpoint that takes social_account_ids. A developer integrating it reads the docs, calls the accounts endpoint once, hardcodes the IDs, and never thinks about it again.

A model does not do that. Given a tool that takes account IDs, a model will invent account IDs. They look plausible. The call succeeds against the schema and posts to the wrong channel, or fails with an error the model then tries to “fix” by inventing different IDs.

So the MCP server needed things the REST API never did:

• A tool whose only job is “tell me what accounts exist”, so the model fetches real IDs instead of guessing. On REST this is a documentation problem. On MCP it is a tool.
• Errors written as instructions, not as status. 422 Unprocessable Entity tells a developer to go read the docs. It tells a model nothing. The message has to say what to do instead.
• A read-before-write tool. The model needs to see the existing queue before adding to it, or it duplicates work a human already did.
• A safe default that is not “publish”. Publishing is irreversible. Scheduling is not. Every agent-created post gets a future timestamp so a human has a window to cancel.

None of that is protocol. It is interface design for a consumer that reasons instead of reading. That is the actual work, and it is why “just wrap your API” produces something that technically connects and practically misbehaves.

If you build on Laravel, I wrote up what broke on my Laravel MCP servers, including the failures that only showed up in production.

What MCP does not give you

Worth saying plainly, because the marketing around this is loose:

• It is not faster. It is another layer over the same HTTP call.
• It does not remove the need for an API. You still built one. MCP calls it.
• It does not make a model reliable. It gives the model a well-described door. It will still walk through the wrong one sometimes.
• It is not required for an AI feature. If your code decides what to call and the model only writes text, you want a normal API call, not MCP.

When to build one, and when not to

Build an MCP server when the model decides which action to take. That is the whole test.

Concretely, it is worth it when:

• Your users already work inside an MCP-capable client — Claude Desktop, Claude Code, Cursor and similar — and want your product reachable from there without switching windows.
• The set of useful actions is larger than one, and which one to take depends on context the model has and your code does not.
• Your API is stable. An MCP server over an API you are still redesigning means maintaining two moving interfaces.

Skip it when:

• Your code picks the endpoint and the model only generates content. Use the API. Adding MCP here is architecture for its own sake.
• You have one action. A single-tool MCP server is a lot of protocol for one HTTP call.
• You do not have an API yet. Build that first. The MCP server is a projection of it, and projecting something that does not exist yet means designing both at once, badly.

The honest summary

MCP is not an API replacement and treating it as one is how people end up disappointed. It is a second interface, aimed at a different consumer, over work you already did.

The value is not the protocol — it is that the runtime tool discovery lets a model use your product without anyone writing an integration first. Whether that is worth building depends entirely on whether models are actually the ones deciding what to call in your product.

For me, on a scheduler where the whole point is that an AI tool writes and queues the post, it clearly was. On a hiring platform where a human clicks the buttons, it clearly was not. JuggleHire has no MCP server for its customers. The only one there is a small, read-only server my own agents use to look up customer records, and it passes the same test: a model decides what to call.

If posting is your use case too, the Schedule & Chill blog walks through how an AI agent gets a post onto a social account, over MCP and over a REST API.

If you want the practical side, I wrote up how to build an MCP server — the structure, the mistakes, and the parts the tutorials skip.