Run it locally with `gig mcp`

The local server is started by your AI assistant on your own computer. It signs in to Gigantics with an email and a password, and talks to the assistant through its standard input and output (stdio). You also get gig admin, a command that runs the same operations from the shell.

If you would rather not install anything, use the remote endpoint instead.

Before you start

The gig program must be installed on the computer where the assistant runs, and be reachable from the assistant (on your PATH, or use its full path).
You need a Gigantics user with an email and password. Instances that only allow LDAP or SAML sign-in cannot be reached this way: use the remote endpoint, which does not need a password.
What the assistant can do depends on the roles of that user. The instance-wide tools (users, Global Settings, licenses, audit) need the Root role. See Roles Configuration.
Your credentials are only sent over https://, or over plain http:// to localhost. For a trusted private network, set GIG_ALLOW_INSECURE_HTTP=1.

Run:

gig admin login --url https://gig.example.com --email admin@example.com

Gigantics asks for the password (it is not shown while you type), checks it, and saves the address, the email and the password in ~/.gig/admin.json. The file is readable only by you (mode 600), and Gigantics refuses to use it if other users can read it.

To remove the stored credentials:

gig admin logout

To see who you are signed in as, and whether that account is Root:

gig admin whoami

If you prefer not to store a password in a file, skip this step and give the credentials to the assistant through environment variables, as in step 2.

Step 2: Add the server to your assistant

Claude Code

claude mcp add gigantics -- gig mcp --url https://gig.example.com

If you did not save the credentials in step 1, pass them as environment variables:

claude mcp add gigantics \
  -e GIG_EMAIL=admin@example.com -e GIG_PASSWORD=... \
  -- gig mcp --url https://gig.example.com

Claude Desktop, Cursor and other MCP clients

Add the server to the MCP configuration of your client (in Claude Desktop: Settings → Developer → Edit Config):

{
  "mcpServers": {
    "gigantics": {
      "command": "gig",
      "args": ["mcp", "--url", "https://gig.example.com"],
      "env": {
        "GIG_EMAIL": "admin@example.com",
        "GIG_PASSWORD": "..."
      }
    }
  }
}

Remove the env block if you signed in with gig admin login. Restart the client after changing its configuration. If the client cannot find gig, write its full path in command.

Step 3: Try it

Ask your assistant:

"Check the health of my Gigantics instance."

If it answers with the version and the sign-in methods of the instance, you are connected.

Options

gig mcp accepts these options:

Option	Description
`--url`, `-u`	The address of the Gigantics server. Default: `GIG_URL`, or `http://localhost:5000`
`--email`, `-e`	The account to sign in with. Default: `GIG_EMAIL`
`--org`, `-o`	The default organization (its moniker), `GIG_ORG`
`--project`, `-p`	The default project (its moniker), `GIG_PROJECT`
`--confirm-mode`	`human` (default) or `agent`. See Approvals and safety
`--verbose`	Writes every tool call to the error output, for troubleshooting
`--list-tools`	Prints the list of tools as JSON and exits. Add `--available` to list only what your account may call
`--version`	Prints the version of the MCP server

The password cannot be given as an option, so it never appears in the process list: use gig admin login or GIG_PASSWORD.

Environment variables

Variable	Description
`GIG_URL`, `GIG_EMAIL`, `GIG_PASSWORD`	The instance and the account. They take precedence over `~/.gig/admin.json`
`GIG_ORG`, `GIG_PROJECT`	The default organization and project
`GIG_MCP_CONFIRM_MODE`	`human` or `agent`, the same as `--confirm-mode`
`GIG_ALLOW_INSECURE_HTTP`	`1` allows sending credentials over plain `http://` to a trusted private network

Working on a project

Most tools work on one project. The assistant finds the organization and project, in this order:

what you said in the request ("in the Sales project..."),
the default of the conversation, which it sets when you choose a project,
the default you started the server with, --org and --project.

If none applies, the assistant asks you which project you mean. You do not need to know ids: it accepts the exact name of anything (a project, a datasource, a job...) and, if a name is partial or ambiguous, it lists the candidates and asks you instead of guessing.

Maintenance tools

Migrations, the server status and the server restart run the gig command next to the MCP server. They are only available when:

the user is Root, and
the server runs on the same machine as the instance and uses a localhost address.

Otherwise the assistant tells you to run them on the instance host.

Administering from the shell: gig admin

gig admin runs the same operations without an assistant, which is handy for scripts and for approving a destructive change yourself with --yes:

gig admin instance health
gig admin job list --project sales --statuses failed

See Admin Command for the commands, options and exit codes.

Troubleshooting

What you see	Cause	Solution
Sign in failed	Wrong credentials, or the instance uses LDAP or SAML	Check them with `gig admin whoami`. For LDAP and SAML instances use the remote endpoint
Refusing to send credentials ... over plain http	The address is `http://` and not `localhost`	Use the `https://` address of the instance
Refusing to read credentials file	Other users can read `~/.gig/admin.json`	Run `chmod 600 ~/.gig/admin.json`
Access denied / `FORBIDDEN`	The account does not have the role that the operation needs	Ask a Root user for the role. The assistant will not try another way around it
Local only on a maintenance tool	The address is not `localhost`, or the user is not Root	Run it on the instance host, or do it from the Gigantics interface
The assistant does not see the server	The client cannot start `gig`	Use the full path of `gig` in `command`, and restart the client

On this page