Create an Invoice with Grok (App and xAI API)

Two ways to use Grok with FreeInvoices

The first path works in the Grok app on grok.com, X, or mobile, with no setup. Grok writes JSON, you paste it into FreeInvoices, and the editor fills in. The second path uses the FreeInvoices MCP server so Grok calls a tool and hands back a ready-made link.

A third path is for developers: the xAI API can call a remote MCP server for you while it answers a request, so a script can draft invoices on a schedule.

Path 1: the import box (any Grok app)

If the JSON says "type": "receipt" (or quote, proforma, credit-note, purchase-order), the matching generator page opens. Your previous draft is saved to local history first. The import runs entirely in your browser; Grok only sees what you type to it.

Do not ask Grok to build a #data= link itself. Language models cannot reliably produce the base64 encoding. Use the import box, or the MCP tool below.

1. Open the FreeInvoices editor and expand the sidebar panel "Import from ChatGPT, Claude…".
2. Click "Copy prompt" and paste it into Grok, then add your details after "Details:" in plain language.
3. Copy Grok's whole reply. Code fences and extra prose around the JSON are fine, because the first { to the last } is parsed.
4. Paste it into "Paste the AI reply" and click "Fill in document".
5. Check the numbers, add a logo, and click Download PDF.

Path 2: add the MCP server as a Grok connector

xAI documents custom MCP connectors for the Grok app. Its connectors page says to go to grok.com/connectors, click "New Connector", select "Custom", then enter the MCP server URL and complete any required authentication. The server must be reachable over the public internet, which https://freeinvoices.app/mcp is.

The FreeInvoices server uses Streamable HTTP and needs no authentication or OAuth. xAI's docs do not say whether a connector with no authentication is accepted, or which plans and apps show the custom option, so if the option is missing, use the import box. On Grok Business and Enterprise, xAI says a team admin must provision connectors first.

1. Go to grok.com/connectors, click "New Connector", and select "Custom".
2. Enter https://freeinvoices.app/mcp as the server URL.
3. In a new chat, describe the invoice. Grok calls the create_document tool.
4. Open the link it returns. The document is pre-filled in your browser, with totals computed. Add a logo and click Download PDF.

https://freeinvoices.app/mcp

Path 3: Grok MCP in the xAI API

xAI's API supports remote MCP servers as a server-side tool. You add a tool of type mcp to the request. In the OpenAI-compatible Responses API (https://api.x.ai/v1), the fields are server_url and server_label (both required), plus optional server_description, allowed_tools, authorization, and headers. In the xAI Python SDK, the same tool is mcp(...) from xai_sdk.tools, and allowed_tools is called allowed_tool_names.

xAI's docs say only Streamable HTTP and SSE servers are supported, and that require_approval and connector_id are not supported in the Responses API. If you omit the allowed-tools list, every tool the server exposes is added to the model's context. FreeInvoices exposes just one, but setting it is still good practice. The docs examples use the model grok-4.7; check the xAI model list for current names.

This sketch follows the structure of xAI's own streaming example. Install the xAI Python SDK (see its GitHub repository), set XAI_API_KEY, and run it.

import os
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp

client = Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(
    model="grok-4.7",
    tools=[
        mcp(
            server_url="https://freeinvoices.app/mcp",
            server_label="freeinvoices",
            allowed_tool_names=["create_document"],
        )
    ],
)

chat.append(user(
    "Create an invoice from Acme Studio to Globex Corp: "
    "monthly retainer for November 2026, 1 x 2500 USD, 8.25% sales tax, "
    "number RET-2026-11, dated 2026-11-01, due 2026-11-15. "
    "Reply with the link the tool returns and the total."
))

for response, chunk in chat.stream():
    if chunk.content:
        print(chunk.content, end="")

Worked example: a monthly retainer

Input: the retainer prompt above. Grok sends the tool a document like the one below. The server returns a link that opens the invoice pre-filled, plus computed totals.

Result from the server: subtotal $2,500.00, tax $206.25 (8.25% of 2,500), total $2,706.25, balance due $2,706.25. No warnings. The server is read-only, stores nothing, and logs no arguments. Your details do pass through freeinvoices.app/mcp to build the link, and the data in the link sits in the URL fragment, which browsers do not send to servers.

{
  "type": "invoice",
  "number": "RET-2026-11",
  "date": "2026-11-01",
  "dueDate": "2026-11-15",
  "currency": "USD",
  "from": "Acme Studio",
  "billTo": "Globex Corp",
  "items": [
    { "description": "Monthly retainer, November 2026", "quantity": 1, "rate": 2500 }
  ],
  "taxRate": 8.25,
  "taxLabel": "Sales tax"
}

Where Grok fits

• Grok app: good for quick drafts from a typed or pasted description, such as a client email thread or a list of jobs.
• xAI API: good for scheduled, repeatable work. A cron job can run the script above for each client and email you the links to review.
• Either way, you review the link before downloading. Totals follow one order: subtotal, minus discount, tax on the discounted amount, plus shipping, minus amount paid, rounded to the currency's minor unit.

Privacy

• Import box: your pasted JSON is parsed in your browser only.
• MCP (connector or API): the invoice details are sent to freeinvoices.app/mcp to build the link. They are not stored.
• Grok and xAI see whatever you type to them. The API call also sends your prompt to xAI.