MCP Server

GitBlixt is a Model Context Protocol (MCP) server. AI agents such as Claude Code connect to it and get tools for your repositories, merge requests, pipelines, deployed apps and AI jobs, so you can ask things like "why is production returning 500s?" and let the agent read the app's logs itself.

The endpoint is https://git.teagles.io/mcp (Streamable HTTP, stateless). It offers one gitlab_api tool that reaches the whole REST API, plus native tools for GitBlixt features the REST API doesn't cover, such as app logs, deploys, AI jobs, wiki pages and server administration.

Connecting a client

Create a personal access token with the read_api scope (read-only) or the api scope (read and write).
Add the server to your client, passing the token as a Bearer token.

Claude Code

claude mcp add --transport http gitblixt https://git.teagles.io/mcp \
  --header "Authorization: Bearer glpat-YOUR_TOKEN"

Add --scope user to make it available in every project. Run claude mcp list, or /mcp inside Claude Code, to confirm it connected and see its tools.

Other clients and shared config

Clients that read an mcpServers JSON config, such as a project's .mcp.json, take:

{
  "mcpServers": {
    "gitblixt": {
      "type": "http",
      "url": "https://git.teagles.io/mcp",
      "headers": { "Authorization": "Bearer ${GITBLIXT_TOKEN}" }
    }
  }
}

Claude Code expands ${GITBLIXT_TOKEN} from your environment, so the token never has to be committed. The client must be able to send a header: GitBlixt doesn't implement MCP's OAuth discovery, so clients that only support OAuth sign-in can't connect.

Checking the connection with curl

curl -X POST https://git.teagles.io/mcp \
  -H "Authorization: Bearer glpat-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

A valid token returns the tools it can use; a missing or invalid one returns 401.

Permissions

The token's scopes decide which tools a client sees. Tools the token can't use are left out of the list entirely, so the agent never tries them.

Tools	Token needs
Read	`read_api` or `api`
Write	`api`
Admin	An admin account with the matching admin permission, plus the scope above

Every tool also checks your role on the project it touches, exactly as the web UI does. For example, reading app logs, deploying and seeing AI job logs need developer access. Through gitlab_api, a read_api token can only make GET requests.

Example prompts

"Show me the errors in the production logs of alice/shop since the last deploy."
"The latest deploy of staging failed. Find out why and fix it."
"Summarize the unresolved threads on merge request !42."
"Pipeline #318 failed. Read the job logs and tell me what broke."
"Redeploy production of alice/shop, then watch the logs for a minute."
"Start an AI review of merge request !42 using my default model."

Tool reference

Project-scoped tools take a project argument: the numeric project ID or its full path, e.g. 42 or "alice/shop". Environments are named as on the project's Environments page.

GitLab API

`gitlab_api` read

Call GitBlixt's GitLab-compatible REST API (GitLab API v4) as the current user. `path` is relative to /api/v4, e.g. "/projects/12/merge_requests" or "/projects/group%2Frepo/issues/3": a "namespace/repo" project id must be URL-encoded ("/" as %2F). Covers projects, repository tree/files/branches/commits/compare, merge requests (notes, discussions, changes, merge), issues, labels, milestones, releases, pipelines and jobs, CI variables, protected branches, webhooks and users. Returns the HTTP status and the decoded JSON body. List endpoints are paginated (20 per page, max 100): pass `page` and `per_page` in `query`, and read the `pagination` object in the result (page, per_page, total, total_pages, next_page, prev_page; next_page is null on the last page, and keys the endpoint does not report are omitted).

Argument	Type	Notes
`method` *	string	One of: GET, POST, PUT, PATCH, DELETE
`path` *	string	Path under /api/v4, starting with "/", without a query string
`body`	object	JSON request body
`query`	object	Query string parameters

Apps & environments

`list_environments` read

List a project's PaaS deployment environments, including active MR previews: branch, status, domains/url, replicas and last deploy.

Argument	Type	Notes
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`get_environment` read

Show one PaaS environment of a project: branch, status, domains/url, replicas, last deploy, port, health check path and whether it has a managed database. Environment variable values are never returned.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`get_app_logs` read

Read the runtime logs (container stdout/stderr) of a deployed PaaS environment, oldest to newest. Returns the most recent `limit` lines matching the filters. Requires developer access to the project.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`http_status`	string	Only lines containing an HTTP status of this class. One of: 2xx, 3xx, 4xx, 5xx
`limit`	integer	Range 1–1000. Default 200
`query`	string	Case-insensitive substring to match
`since`	string	ISO 8601 timestamp; only lines at or after it
`source`	string	One of: stdout, stderr, system
`until`	string	ISO 8601 timestamp; only lines at or before it

`list_deployments` read

List recent deploys of a PaaS environment, newest first: status, commit sha, ref and timing. Failed deploys include the tail of the deploy log when you have developer access.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`limit`	integer	Range 1–50. Default 10

`deploy_environment` write

Deploy the latest commit of a PaaS environment's branch, like the Deploy button. The deploy runs asynchronously; follow it with list_deployments. Environments that require approval report status awaiting_approval until a reviewer approves.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`stop_environment` write

Stop a PaaS environment, like the Stop button: removes its running service. Deploy it again to bring it back.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`restart_environment` write

Restart a running PaaS environment's containers on the same image and environment variables. To pick up new code or changed variables, deploy instead.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`update_environment` write

Change a PaaS environment's settings: branch, domains, port, replicas, health check path, auto deploy, skip smoke test and build platform. Only the settings given change. They take effect on the next deploy (deploy_environment).

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`auto_deploy`	boolean	Deploy on every push to the branch
`branch`	string	Branch to deploy; empty for the project's default branch
`build_platform`	string	Docker platform to build for, e.g. "linux/amd64"; empty for the host's
`domains`	array of string	Every domain the environment serves, replacing the current list
`health_check_path`	string	Path the smoke test and health checks request, e.g. "/up"; empty resets it to "/health"
`port`	integer	Range 1–65535
`replicas`	integer	Range 0–10
`skip_smoke_test`	boolean	Deploy without first checking the new image answers the health check

App email

`get_email_setup` read

Show a PaaS environment's email setup: provider, sending domain, From address, status (pending_dns, verifying, issuing, verified or failed), the last error, the DNS records to publish and, once verified, the env vars written. Needs developer access and the feature:manage_email permission. Secrets are never returned.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`set_up_email` write

Set up outbound email for a PaaS environment, replacing any earlier setup. Registers the sending domain with the provider and returns the DNS records to publish (publish_email_dns adds them to Cloudflare). Verification is then checked automatically for 72 hours; once verified, SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD and MAIL_FROM are written to the environment, which picks them up on its next deploy. mailgun and ses use your stored credential (save_email_credential); smtp takes host, port, username and password. Not available on preview environments.

Argument	Type	Notes
`domain` *	string	Sending domain; a subdomain such as mail.example.com is recommended
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`provider` *	string	One of: mailgun, ses, smtp
`dkim_records`	array of object	smtp only: the provider's DKIM records as {type, name, value} objects, named under <domain>'s _domainkey
`from`	string	MAIL_FROM address at the domain; defaults to noreply@<domain>
`host`	string	smtp only
`password`	string	smtp only
`port`	integer	smtp only. Range 1–65535
`spf_include`	string	smtp only: the provider's SPF include host, e.g. spf.example.com
`username`	string	smtp only

`check_email_setup` write

Ask the provider now whether an environment's sending domain is verified, instead of waiting for the automatic check. Once it is, the SMTP env vars are written; deploy the environment to pick them up.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`publish_email_dns` write

Add an environment's email DNS records (SPF, DKIM, DMARC) to the domain's Cloudflare zone with your stored Cloudflare credential (save_email_credential with an API token that can edit DNS, or connect Cloudflare in the web UI), then check verification. Returns each record's outcome.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`request_ses_production_access` write

For an Amazon SES email setup, ask AWS to move the account out of the SES sandbox (where mail only reaches verified addresses). AWS reviews the request manually. Only the person who set up the email may request it, as it acts on their AWS account.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`website_url` *	string	The app's public URL, shown to AWS in the request

`remove_email_setup` write

Delete a PaaS environment's email setup. The domain and sending credentials at the provider, the DNS records and the SMTP env vars already written are left in place.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`list_email_credentials` read

List your stored email setup credentials (mailgun, ses, cloudflare) with their region and last update. Secrets are never returned.

`save_email_credential` write

Store your credential for an email setup provider, encrypted, replacing any earlier one. It is tested first, so a bad key never replaces a working one. mailgun: api_key and region (us or eu). ses: access_key_id, secret_access_key and region (e.g. us-east-1). cloudflare: api_token with DNS edit access.

Argument	Type	Notes
`provider` *	string	One of: mailgun, ses, cloudflare
`access_key_id`	string	ses
`api_key`	string	mailgun
`api_token`	string	cloudflare
`region`	string	mailgun and ses
`secret_access_key`	string	ses

`delete_email_credential` write

Delete your stored credential for an email setup provider. Pending mailgun or ses setups that use it fail at their next check; verified ones keep sending.

Argument	Type	Notes
`provider` *	string	One of: mailgun, ses, cloudflare

Databases

`describe_database` read

Describe a PaaS environment's database (Postgres or MariaDB). Without table: its schemas with their tables and views. With table: its columns, indexes, foreign keys, row estimate and size. Read data with query_database. An admin must enable the DB editor for environments and grant you the db_admin:environments permission, and you need developer access to the project. Not available to project-restricted (AI job) tokens.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`schema`	string	Schema (on MariaDB, the database) to describe. Default: every schema, or public (MariaDB: the connected database) when table is given
`table`	string	Table to describe in detail

`query_database` read

Run one SQL statement against a PaaS environment's database (Postgres or MariaDB). Read-only by default: only SELECT, WITH, SHOW, EXPLAIN, DESCRIBE, VALUES and TABLE statements run, inside a READ ONLY transaction that is always rolled back, with a 30 second statement timeout; ones that write files, cancel or terminate backends, take session locks or call dblink_exec/lo_export are refused. Set allow_write to change data: that needs a token with the api scope, commits immediately, and runs only INSERT, REPLACE, MERGE, and UPDATE/DELETE with WHERE; use the browser DB editor for anything else. Rows are capped at limit (truncated is true when more exist). Binary values, Postgres uuids included, come back as \x-prefixed hex; cast them to text for readable output. Every query is recorded in the DB editor audit log. An admin must enable the DB editor for environments and grant you the db_admin:environments permission, and you need developer access to the project. Not available to project-restricted (AI job) tokens.

Argument	Type	Notes
`environment` *	string	Environment name, e.g. "production"
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`sql` *	string	One SQL statement
`allow_write`	boolean	Run outside the read-only transaction so INSERT/UPDATE/DELETE take effect. Needs the api scope.. Default false
`limit`	integer	Most rows to return. Range 1–1000. Default 100

AI jobs

`run_ai_job` write

Start an AI agent job on a project, like the "Fix with AI" / "Review with AI" buttons: fix_issue fixes an issue on a new branch and opens a merge request (needs issue_iid); review_mr reviews a merge request at the chosen review_depth and posts the review as notes, fix_mr applies its review feedback as new commits (both need merge_request_iid); freeform runs an open-ended prompt on a new branch off `branch` (default: the project's default branch) and opens a merge request into that branch only if the agent changed code — otherwise its answer is the job's result_summary. provider, model and effort default to your last-used selection. Runs asynchronously; follow it with get_ai_job. Requires developer access.

Argument	Type	Notes
`job_type` *	string	One of: fix_issue, review_mr, fix_mr, freeform
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`background`	boolean	Fix jobs only: run in the background (default) or show live. Default true
`branch`	string	Existing branch to work from and open the merge request into (freeform; defaults to the project's default branch)
`dry_run`	boolean	review_mr only: runs the review and stores it on the job without posting anything to the merge request, for benchmarking. Cannot be combined with auto-merge. Default false
`effort`	string	One of: low, medium, high, xhigh, max
`issue_iid`	integer	Issue to fix (fix_issue)
`merge_request_iid`	integer	Merge request to review or fix (review_mr, fix_mr)
`model`	string	Model id; required except for Anthropic
`prompt`	string	What the agent should do (freeform, required)
`provider`	string	Slug of one of your AI provider keys, e.g. "anthropic"
`review_depth`	string	review_mr only; defaults to your AI settings. quick: One agent reviews the diff with a secrets scan and semgrep, without compiling or running tests; about 5 to 10 minutes. moderate: Parallel subagents review the diff after compiling and running the project's static analysis; about 20 to 40 minutes. thorough: Everything in Moderate, plus the tests that cover the change, run against a provisioned test database; about 40 to 75 minutes.. One of: quick, moderate, thorough

`list_ai_jobs` read

List a project's AI agent jobs, newest first: type, status, provider/model, result summary and timing. Requires developer access.

Argument	Type	Notes
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`limit`	integer	Range 1–50. Default 20
`status`	string	One of: pending, running, success, failed, canceled

`get_ai_job` read

Show an AI agent job: status, type, provider/model, timing, result summary, exit code, the branch and merge request it worked on or created, and the last lines of its log. Requires developer access.

Argument	Type	Notes
`id` *	integer
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`log_tail_lines`	integer	Range 0–2000. Default 200

`get_ai_job_log` read

Read an AI agent job's full log in pages of lines, oldest first, optionally filtered by a case-insensitive substring. get_ai_job only returns the tail; use this for the hunt phase of a review or anything earlier in a run. Requires developer access.

Argument	Type	Notes
`id` *	integer
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`limit`	integer	Maximum number of lines to return. Range 1–2000. Default 500
`offset`	integer	Index of the first line to return; counts only matching lines when query is given. Range 0–. Default 0
`query`	string	Case-insensitive substring to match

`cancel_ai_job` write

Cancel a pending or running AI agent job, stopping its container. Allowed for the job's creator and developers of the project.

Argument	Type	Notes
`id` *	integer
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

Wiki & snippets

`list_wiki_pages` read

List a project's wiki pages (title and slug). Read one with get_wiki_page.

Argument	Type	Notes
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"

`get_wiki_page` read

Read a project wiki page's Markdown content by its slug.

Argument	Type	Notes
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`slug` *	string	Page slug, e.g. "getting-started"

`write_wiki_page` write

Create or update a project wiki page. Updates the page at `slug` when it exists, otherwise creates it; `slug` defaults to one derived from the title. Content is Markdown. Requires developer access.

Argument	Type	Notes
`content` *	string	Markdown; replaces the page body
`project` *	integer or string	Project id or full path, e.g. 42 or "group/repo"
`title` *	string
`slug`	string	Lowercase letters, numbers, - and _; pass it to update a page

`list_snippets` read

List code snippets: your own (any visibility) and everyone's public ones, newest first, without content. Read one with get_snippet.

Argument	Type	Notes
`limit`	integer	Range 1–100. Default 50

`get_snippet` read

Read a code snippet with its content: public, internal (any signed-in user) or your own.

Argument	Type	Notes
`id` *	integer

`write_snippet` write

Create a code snippet, or update one of your own by passing its id. Visibility: private (default, only you), internal (signed-in users) or public.

Argument	Type	Notes
`content` *	string
`title` *	string
`description`	string
`file_name`	string	Used for syntax highlighting, e.g. "notes.md"
`id`	integer	Snippet to update; omit to create
`visibility`	string	One of: public, internal, private

Search

`search` read

Search the projects, issues and merge requests (by title and description) or code (files on default branches that match) you can see. Pass project to search one project.

Argument	Type	Notes
`query` *	string
`scope` *	string	One of: code, issues, merge_requests, projects
`limit`	integer	Range 1–50. Default 20
`project`	integer or string	Project id or full path, e.g. 42 or "group/repo"

Admin

`get_server_logs` admin, read

Admin only: read GitBlixt's own server logs (its Docker container/service output), oldest to newest, optionally filtered by a case-insensitive substring. Covers the most recent 5000 lines.

Argument	Type	Notes
`limit`	integer	Range 1–1000. Default 200
`query`	string	Case-insensitive substring to match

`list_backups` admin, read

Admin only: list GitBlixt backups, newest first: status, storage, contents, size, timing and any error.

Argument	Type	Notes
`limit`	integer	Range 1–100. Default 20

`start_backup` admin, write

Admin only: start a backup of the database, git repositories and/or uploads. Runs asynchronously; follow it with list_backups.

Argument	Type	Notes
`includes`	array of string	What to back up; defaults to all three. Any of: database, repos, uploads

* required

Databases

describe_database and query_database give the same access to an environment's database as the browser DB editor, and need the same setup:

An admin turns on the DB editor for environments under Admin → Settings → DB editor.
Your account has the db_admin:environments admin permission, and you have write access to the project.

Queries are read-only unless allow_write is set, which needs an api token. Reads can't write files, cancel or terminate other connections, or take session locks. With allow_write, only INSERT, REPLACE, MERGE, and UPDATE/DELETE with a WHERE run; schema changes and everything else go through the browser editor. Every query is recorded in the DB editor's audit log. Database credentials are never returned.

AI jobs

Every AI job gets this server automatically, with nothing to configure. Its token is created when the agent starts and deleted when it finishes. It is read-only and restricted to the job's repository, so the agent can read issues, merge request threads, CI logs and app logs but can't change anything, read CI variables or webhooks, use admin, database, snippet or email-credential tools, or reach other projects.

Agent containers connect to https://git.teagles.io/mcp. If they can't reach GitBlixt's public address, for example in a local Docker Compose setup, set Admin → Settings → AI Settings → Agent base URL to an address they can reach, such as http://gitblixt:4000. The GITBLIXT_AGENT_BASE_URL environment variable is the fallback for fresh installs.

Limits and troubleshooting

The endpoint allows 120 requests a minute. gitlab_api calls also count toward the REST API's own limit.
401 Unauthorized: the token is missing, mistyped, revoked or expired.
A tool is missing from the list: the token lacks the scope for it, it's an admin tool and the account isn't an admin, or it's an AI job token and the tool isn't bound to one project.
"Deployment is not enabled for this project": the app tools only work for projects with deployments turned on in their settings.
"You need at least developer access to this project": the tool needs a higher project role than the token's user has.
"This token is restricted to project N": an AI job token was used outside its own repository.

Administration

Using GitBlixt

Account

Integrations

Reference

MCP Server

Connecting a client

Claude Code

Other clients and shared config

Checking the connection with curl

Permissions

Example prompts

Tool reference

GitLab API

gitlab_api read

Apps & environments

list_environments read

get_environment read

get_app_logs read

list_deployments read

deploy_environment write

stop_environment write

restart_environment write

update_environment write

App email

get_email_setup read

set_up_email write

check_email_setup write

publish_email_dns write

request_ses_production_access write

remove_email_setup write

list_email_credentials read

save_email_credential write

delete_email_credential write

Databases

describe_database read

query_database read

AI jobs

run_ai_job write

list_ai_jobs read

get_ai_job read

get_ai_job_log read

cancel_ai_job write

Wiki & snippets

list_wiki_pages read

get_wiki_page read

write_wiki_page write

list_snippets read

get_snippet read

write_snippet write

Search

search read

Admin

get_server_logs admin, read

list_backups admin, read

start_backup admin, write

Databases

AI jobs

Limits and troubleshooting

`gitlab_api` read

`list_environments` read

`get_environment` read

`get_app_logs` read

`list_deployments` read

`deploy_environment` write

`stop_environment` write

`restart_environment` write

`update_environment` write

`get_email_setup` read

`set_up_email` write

`check_email_setup` write

`publish_email_dns` write

`request_ses_production_access` write

`remove_email_setup` write

`list_email_credentials` read

`save_email_credential` write

`delete_email_credential` write

`describe_database` read

`query_database` read

`run_ai_job` write

`list_ai_jobs` read

`get_ai_job` read

`get_ai_job_log` read

`cancel_ai_job` write

`list_wiki_pages` read

`get_wiki_page` read

`write_wiki_page` write

`list_snippets` read

`get_snippet` read

`write_snippet` write

`search` read

`get_server_logs` admin, read

`list_backups` admin, read

`start_backup` admin, write