Connect with an MCP API key

The remote endpoint lets an AI assistant connect straight to your Gigantics instance. There is nothing to install: you turn the endpoint on, create a key, and paste a command or a snippet into your assistant.

An MCP API key acts as the Root user that created it, with access to the whole instance. Treat it like a password.

Before you start

You must be a Root user. Only Root users can open Global Settings and create MCP keys.
Your instance must be served over HTTPS, directly or behind a proxy that terminates TLS (see Nginx Configuration). Plain http:// is only accepted from the instance machine itself.
Your assistant must be able to connect to an MCP server over HTTP and send a custom Authorization header. Claude Code, Cursor and VS Code can.

Step 1: Turn on the endpoint

Click your avatar and select Global Settings.
Open the MCP section in the sidebar.
Turn on Remote MCP endpoint.

The page shows the address your assistant has to use, for example https://gig.example.com/mcp. Click Copy to copy it.

┌─────────────────────────────────────────────────────────────────┐
│ MCP                                                 [Create key] │
│ Let remote MCP clients administer this instance with an API key  │
├─────────────────────────────────────────────────────────────────┤
│ [ON]  Remote MCP endpoint                                        │
│ [ https://gig.example.com/mcp                         ] [Copy]   │
├─────────────────────────────────────────────────────────────────┤
│ Name        │ Key           │ Acts as │ Destructive tools │ ...  │
│ Claude Code │ gigmcp_4f8a_… │ Ana     │ Person approves   │ ...  │
└─────────────────────────────────────────────────────────────────┘

The endpoint is off by default. While it is off, /mcp does not exist on your server.

If you open the page over plain http:// from another machine, the page warns you: the endpoint refuses plain HTTP, so serve the instance over HTTPS first.

Step 2: Create a key

Click Create key.
Fill in the form:

Field	Description
Name	A name that tells you where the key is used, for example Claude Code on my laptop (required, up to 100 characters)
Expires	30 days, 90 days (default), 1 year or Never. A key that expires stops working on that date
Allow agent mode	Off by default. With it off, a person approves every destructive tool call. See Approvals and safety before turning it on

Click Create key.

Gigantics shows the new key, which looks like gigmcp_4f8a21c9_…, together with ready-to-use connection commands.

The key is shown only once. It cannot be retrieved after you close the window. Copy it and store it in a password manager before clicking Yes, I copied the key and saved it.

You can have up to 20 MCP API keys. Create one key per assistant or per person, so you can remove one without affecting the others.

Step 3: Connect your assistant

Claude Code

Run this command in your terminal. The window of step 2 shows it already filled in with your address and key:

claude mcp add --transport http gigantics https://gig.example.com/mcp \
  --header "Authorization: Bearer gigmcp_..."

Other MCP clients (Cursor, VS Code, ...)

Add this to the MCP configuration of your client:

{
  "mcpServers": {
    "gigantics": {
      "type": "http",
      "url": "https://gig.example.com/mcp",
      "headers": { "Authorization": "Bearer gigmcp_..." }
    }
  }
}

The exact place and format of that file depend on the client. Check its MCP documentation if it does not accept this snippet as is.

Some hosted assistants (for example the web version of an assistant) can only connect with OAuth and cannot send a static Authorization header. They cannot use MCP API keys yet.

Step 4: Try it

Ask your assistant:

"Check the health of my Gigantics instance."

It should answer with the version of the server and the sign-in methods in use. If it does, you are connected. The Last used column of the key list now shows the time of the request.

Managing keys

The key list shows one row per key:

Column	Description
Name	The name you gave the key
Key	The start of the key, `gigmcp_<prefix>_…`, to recognize it. The rest is never shown again
Acts as	The Root user that created the key
Destructive tools	Person approves (default) or Agent mode (orange)
Expires	When the key stops working, Never, or Expired if it already did
Last used	How long ago it was used. Hover to see the IP address
Created On	When the key was created

To remove a key, open the ⋮ menu of its row and select Delete, then confirm with Yes, delete. Clients that use it stop working at once, and its open sessions are closed.

A key also stops working, without being deleted, when:

it expires,
the user it acts as is no longer a Root user or is deleted,
you turn off Remote MCP endpoint. Turn it on again and the keys work again.

Creating and deleting keys is recorded in the Events with the source Auth. The key itself is never recorded.

What is different from the local server

The remote endpoint has the same tools, approvals and views as the local server, with these differences:

No maintenance tools. Running migrations, checking the server processes and restarting the server would run on the machine of the server, so they are not offered. Do them from the instance host.
The key decides the approval mode. There is no server-wide switch: a key is either Person approves or Agent mode.
When a request is refused, the assistant points you to the Gigantics interface instead of the gig admin command.

How the endpoint is protected

Protection	What it means for you
Strong, stored hashed	Keys have 256 random bits. Gigantics only stores a hash, so even someone with access to the database cannot read them
Header only	The key is read from the `Authorization` header, never from the URL, so it does not end up in logs
HTTPS required	Requests over plain HTTP from other machines are refused
Brute force limit	After 10 wrong keys from the same address in 5 minutes, that address is blocked for a while (HTTP 429)
No browsers	Requests coming from a web page of another site are refused. Native assistants are not affected
Same permission checks	The endpoint runs each call as the key's Root user through the normal permission checks. The key is not accepted anywhere else (for example `/graphql`)
Sessions	A connection is bound to its key, closes after 30 minutes without activity, and the instance allows up to 10 per key

Troubleshooting

What you see	Cause	Solution
404	Remote MCP endpoint is off	Turn it on in Global Settings → MCP
401 Invalid MCP API key	The key is wrong, deleted, expired, or its owner is no longer Root	Check the key and its Expires column, or create a new one
401 An MCP API key is required	The client does not send the `Authorization` header	Check the `headers` of your client configuration
403 needs HTTPS	The instance is reached over plain HTTP from another machine	Use the `https://` address, or put the instance behind a TLS proxy that sends `X-Forwarded-Proto: https`
403 Origin not allowed	The request comes from a web page of another site	Use a native assistant instead of a browser-based tool
429	10 wrong keys from the same address	Wait for the time in the `Retry-After` header and fix the key
The client reconnects or gets a 404 on later requests	The instance runs several web workers (`gig start --web=N`) and the request reached another one	Run one web worker, or ask your administrator to route each client to the same worker

On this page