alasin-mcp
Provides branch-and-commit access to a Forgejo instance: list repositories, branches and folders; read files and diffs; create work branches; and commit multiple files in a single commit, while avoiding merges, deletions, settings changes and secrets.
Provides branch-and-commit access to a Gitea instance: list repositories, branches and folders; read files and diffs; create work branches; and commit multiple files in a single commit, while avoiding merges, deletions, settings changes and secrets.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
alasin-mcp
A remote, multi-tenant MCP server that gives AI agents branch-and-commit access to a Forgejo or Gitea instance.
An agent can read repositories, create a work branch and commit several files to it in one commit. It can't merge, delete, change settings or touch secrets: a person reviews and merges the branch. Alasin is Finnish for "anvil".
It's a change lane for people who can't push to the upstream (GitHub) repository themselves. The server's instructions and tool descriptions tell a model that can push upstream to change it there instead, and to use alasin only for reading.
Transport: Streamable HTTP (stateless) at
/mcp. People sign in through its OAuth front door (origo, with your OIDC provider upstream); it can also sit behind an OAuth gateway that forwards a bearer token, or verify JWTs from your identity provider.Multi-tenant: one deployment serves many tenants, each with its own Forgejo. The tenant comes only from the verified token.
Audited and traced: every tool call is an OpenTelemetry span and an append-only audit event; commits carry a
Trace-Idtrailer.
Licence: Apache-2.0.
Tools
Every result stays well under a client's tool-result limit (claude.ai cuts at about
25k tokens). The caps are server-side and measured as JSON on the wire, where a quote,
backslash or tab takes two bytes and other control characters six. The SDK sends a
structured result twice (text and structuredContent), so each copy stays under about
28 KB of content and both together under 60 KB. A result that was cut says
truncated: true.
Tool | Kind | What it does |
| read | Who the server thinks you are: subject, IdP subject, name and email, tenant, auth mode, the groups in your sign-in token ( |
| start | Opens a work session. Returns |
| read | Repositories the tenant may reach (the tenant's allowlist ∩ what the Forgejo account can see). |
| read | Branches, with whether each is protected. |
| read | A folder's entries at a ref (default branch by default), at most 500 and within the budget ( |
| read | A file at a ref; text as UTF-8, anything else as base64, in parts that fit the budget. Text: |
| read | A branch's commits and a unified diff per file against the default branch (or |
| write | A new branch from the default branch (or |
| write | One commit with several files ( |
| write | Plain git (tenants with |
| read | Follow a branch from push to merge: its head |
| write | Open an upstream pull request from your own branch (tenants with |
Not provided, by design: merging, deleting branches, files or repositories, repository
settings, administration, webhooks and Actions secrets. File deletion and renames are
not exposed either (the contents API's delete operation and from_path are never sent).
Commit messages get trailers added by the server:
Update the headline
Co-Authored-By: Claude <noreply@anthropic.com>
Trace-Id: 0af7651916cd43dd8448eb211c80319c
Alasin-Session: ws_7ZBUuDKkAf-wwjrEiPQ15Uz5The model can't set Trace-Id or Alasin-Session itself; a message containing them is
refused.
Related MCP server: forgejo-mcp
Plain git
For a client with a real shell and git (claude.ai's code sandbox, for one),
git_access turns a work branch into an ordinary git remote:
git clone --branch lane/change-1a2b3c4d https://x-token:<credential>@alasin.example.com/git/acme/site.git
git config user.name "Jane Doe"; git config user.email jane@example.com # from git_config
# edit, git commit ...
git push origin lane/change-1a2b3c4dThe credential is random (32 bytes), stored only as its SHA-256, and valid for
ttl_seconds(15 minutes by default) for one person, one repository and one branch. It reads the whole repository (every branch, as clone and fetch do) by design, and pushes only that branch. It sits in the URL's user part, so git sends it as HTTP Basic auth and it never appears in a request path or an access log. When it expires, callgit_accessagain andgit remote set-url origin <new clone_url>.Read-only access (
access="read") mints a credential bound to no branch. Everygit-receive-packroute answers it 403 ("read-only access: call git_access with access='write' to push") before anything reaches Forgejo.The result is a playbook.
stepslists the commands in order: a shallow clone with a generous timeout, reading the repository's ownCLAUDE.md/AGENTS.md/README.mdfirst, committing, fetching before a push, and thenchange_statusandpropose_change.errorsmaps this server's 401, 403 and 429 answers and a rejected non-fast-forward to what to do.Routes: only git's smart HTTP under
/git/<owner>/<repo>.git/:info/refs(exactly oneservice,git-upload-packorgit-receive-pack),git-upload-packandgit-receive-pack. No dumb HTTP, no LFS. The client's query string is never forwarded; the server builds?service=itself. A missing or expired credential gets401with a Basic challenge; one client address may fail 30 times a minute before it gets429(successes don't count: sandboxes share addresses).Forwarding: to the tenant's Forgejo with the tenant's service token (re-read on every request); the caller's credential never leaves the server. Request and response bodies are streamed; a push is capped at
max_push_bytes.Pushes are checked before anything reaches Forgejo. Every ref command must update exactly
refs/heads/<the credential's branch>: no other branch, no tag, no new branch, no deletion, no shallow or signed pushes. Capabilities are an allowlist (report-status,report-status-v2,side-band-64k,side-band,quiet,atomic,ofs-delta,agent,object-format,session-id, by name before any=): push options in particular are refused, because Forgejo applies options such asrepo.privateas the pusher, the service account. The branch's owner is checked again at every push. A refused push is answered in git's report-status format, so git prints! [remote rejected] ... (<reason>). Forgejo's branch protection still decides what the push may change (protected file patterns, force pushes).Audit: each push writes an attempt event before it is forwarded (no audit, no push) and an outcome event after, also when the client disconnects early. A clone or fetch is recorded at its
info/refsrequest, and the firstgit-upload-packPOST per credential each minute is recorded too, since a protocol v2 client can fetch withoutinfo/refs(one event per window, not one per negotiation round). Events carry the person's subject, the repo, the branch's digest and the old and new commit ids; never the credential.Limits:
requests_per_minuteper person on the proxy, and one push at a time per person and branch, however many credentials they hold.Commit authorship inside a push is whatever the client sets.
git_accessreturns the signed-in person's name and email asgit_config, the audit records who really pushed, and the lane's proposer re-checks a branch before anything reaches GitHub; the server does not rewrite or verify the author fields of pushed commits.The credential passes through the model's context (the sandbox has nowhere else to keep it). Its short life and narrow grant are the mitigation: it can only update that person's own work branch, which Forgejo's protection limits further.
Requires auth_mode = "service_account" and branch_owners = true.
Security model
Identity. Every request to /mcp needs Authorization: Bearer <token>. A
TokenVerifier turns the token into a Principal(tenant, subject, name, email). The
principal is attached to that HTTP request only; tools read it from the request that
carried their call, so concurrent requests can't see each other's identity. No tool has
a tenant, host or URL argument, and headers can't change the principal.
Tenancy. A TenantResolver maps the principal to the tenant's settings: Forgejo
base URL, auth mode, credentials and policy. The Forgejo URL comes only from there. A
repository argument is validated as owner/name (no URLs, no ..) and checked against
the tenant's allowlist, so naming another tenant's repository or host reaches nothing
outside the caller's own Forgejo.
Isolation.
Work sessions, stored tokens and cache entries are keyed by
(tenant, subject). A session ID presented by any other principal is "unknown".Stored tokens (user-delegated mode) are encrypted with AES-256-GCM under a per-tenant data key. Each data key is wrapped by a master key (envelope encryption). The associated data binds every ciphertext to its tenant and subject, so a row copied to another tenant or subject fails to decrypt. Swap
LocalKeyWrapperfor a KMS client by implementingKeyWrapper.Rate limits are per tenant. Audit files are written per tenant.
tests/test_cross_tenant.pyfails if a valid token for tenant A can reach tenant B's Forgejo, cache, session or stored token, including through B's repository or host named in an argument, and under concurrent interleaved calls.
Writes. The server refuses writes to the default branch, to branches matching
protected_branches, to branches outside branch_prefix (when set), and to existing
branches the account can't push to. This is defence in depth: Forgejo's branch
protection and protected file patterns are the real gate, and they apply to the
contents API too (a commit touching a protected path is rejected with 403).
CI workflow folders. Files under .forgejo/, .gitea/ and .github/ (any case)
are refused by default, because a forge with Actions enabled runs them, with the
repository's secrets. A tenant can opt in with allow_ci_paths = true, or change the
list with ci_paths. Protect these paths in Forgejo as well.
Request size. Bodies over server.max_request_bytes (default 8 MiB) are refused with
413 before authentication. Only HTTP is served; WebSocket connections are closed.
Outbound requests. Every value placed in a Forgejo URL is validated and percent-encoded per segment. The HTTP client never follows redirects, so a token can't be carried to another host.
Audit. One outcome event per tool call, success, failure or cancellation: time,
tenant, who called (sub, the person's Keycloak subject, for a person signed in through
the identity provider; otherwise subject, the static credential's or OAuth client's
configured subject), client address, tool, session ID, trace and span IDs, arguments,
outcome, result summary, repository, commit, author source and auth mode.
Audit events carry no personal data: no name, email or username, and no free text that
could hold one. Commit messages, intents, branch names, refs, file paths, error messages
and any other text are recorded as <key>_sha256 and <key>_chars (an error also has a
fixed error_kind); author arguments only as author_given; author and committer not
at all (the commit records them; commit locates it). File contents are recorded as size
and SHA-256, not copied. A short branch name's SHA-256 can be guessed from a list of
likely names: the commit SHA, not the branch, is what locates a change.
Values a caller chooses are written only in their own narrow shape, otherwise as a digest:
grant_type only as one of authorization_code, refresh_token, client_credentials;
client_id only as a configured client, or on the outcome of a token origo issued for it
(an attempt or a refusal names it only as a digest: anyone can send any id); session_id
only as a live session of the caller's (alasin's exact ws_ + 24-character id); repo, and
a result's url, only when the tenant's configuration names the owner (an argument's repo
always as its SHA-256); client_ip only as an IP address. Nested arguments and results get
the same rules.
client_ip is the raw address in the local file; the Muutto365 audit-log gateway replaces
every IP address with a keyed hash before the record reaches the object-locked bucket.
Authorization links and OAuth state never reach audit events or span status. Spans
(telemetry, not the audit trail) still carry branch, author and committer.
Sign-ins through the OAuth front door are audited too, in the same two phases. Before
origo sees a /token request, an attempt event (grant type, client ID, client address)
is written; if it can't be, the client gets 503 and no code or refresh token is spent.
After origo answers, an outcome event names the person the token speaks for by their
sub alone (sign_in or token_refresh). A token that can't be attributed is never delivered (503). If only
the outcome can't be recorded, a sign-in gets 503 (a fresh authorization fixes it) and a
refresh gets its token, logged: origo has already rotated the refresh token, so
withholding it would end the session.
Writes fail closed. Before any mutating Forgejo call (creating a branch, committing) an attempt event is written; if it can't be recorded, the write isn't made. The outcome event is written afterwards whatever happens. If only the outcome can't be recorded, the call still returns its result, because the write has landed and an error would invite a retry that duplicates it; the attempt event is the record. Every sink is tried; only a failure of a required sink (the JSONL file) counts as a failure. stderr is best effort.
Auth modes
Chosen per tenant with auth_mode.
Mode | Forgejo credential | Commit author | Committer | Status |
| one token per tenant | the service account, or a trusted override (below) | the service account | implemented |
| Forgejo OAuth2 per person (authorization code + PKCE), stored encrypted, refreshed | the person | the person | implemented, unit-tested; not yet run against a live Forgejo OAuth app |
| short-lived per-repository token from a | the end user from the verified token | the platform bot | interface only; no minter ships |
Service-account author override. By default the service account authors commits.
author_source lets the deployer choose a trusted source for the author; the committer
stays the service account (as GET /user reports it, or the configured
service_committer, which is not checked against the token's account) and the audit
records both:
token_claims:nameandemailfrom the verified inbound token (JWT verifier, or the OAuth front door's identity provider). The token must carryemail_verified: true(origo includes the email only when the IdP verified it).trusted_header: aName <email>header named byauthor_header. It is honoured only from callers that authenticated with an[[auth.static]]credential markedgateway = true; any other caller sending it is refused, and the config won't load without such a credential. Your gateway must set this header itself and strip any copy sent by clients.tool_argument:author_nameandauthor_emailtool arguments. The model controls these; use only when that is acceptable. Without this opt-in the arguments are refused.
User-delegated mode. When a person has no token yet, tools return a Forgejo
authorization link. Forgejo redirects to /oauth/forgejo/callback; the server exchanges
the code, then checks that the Forgejo account's match_field (default email) equals
the caller's match_claim. When matching on email, the caller's token must carry
email_verified: true and the address must be a verified address of the Forgejo account
(GET /user/emails). That check stops a link opened by someone else from binding their
Forgejo account to your subject. Refreshes are serialised per person; a refresh that
Forgejo rejects with invalid_grant drops the stored token, while any other failure
(an outage, for example) keeps it. Register an OAuth2 application in Forgejo with
the callback URL as its redirect URI. Requires server.master_key_*.
Platform-scoped mode. Implement alasin_mcp.credentials.TokenMinter:
class TokenMinter(Protocol):
async def mint(
self, tenant: TenantConfig, principal: Principal, repo: RepoRef
) -> MintedToken: ...and name a factory package.module:factory (called with the TenantConfig) in the
tenant's platform.minter. Without one, calls fail with a clear "no token minter is
configured" error. Tokens are per repository, so list_repos isn't available in this
mode. The author's email must be verified (email_verified: true).
Branch creation
Chosen per tenant with branch_creation:
api(default): the server's Forgejo account creates the branch.webhook: for setups where another service must create branches. The server sendsPOST <branch_webhook.url>with the JSON body{"tenant", "repo", "branch", "from_ref", "session_id", "subject"}, plusowner_subwhen the caller signed in through the identity provider (see OAuth sign-in): the person's own subject at the IdP, for Keycloak the user ID, without origo's<issuer>|prefix. The headers:X-Alasin-Timestamp: Unix seconds.X-Alasin-Signature:sha256=followed by the hex HMAC-SHA256 of"<timestamp>." + body, keyed with the tenant's webhook secret.
The secret is re-read on every call. After a 2xx reply the server polls Forgejo until the branch exists, up to
timeout_seconds. The receiver should verify the signature and reject stale timestamps.
To add another strategy, implement alasin_mcp.branching.BranchCreator and register it
in Services.branch_creators under a name tenants can select.
Branch owners. With branch_owners = true, only the subject that created a branch
through this server may commit to it. Owners are kept in server.state_path.
Before creating a new branch,
create_branchreserves it for the caller, so a second person can't start the same creation. A reservation is never ownership: nobody, the reserver included, may commit to a branch that is only reserved. Once the creator answers with success, the caller is confirmed as the owner. If creation fails, the reservation is dropped. A reservation left behind by a crash expires after the creator's time limit plus a minute, and never counts in the meantime.commit_filesrefuses a branch whose confirmed owner is someone else, and a branch with no confirmed owner: one that is still being created, one created outside this server or before the setting was on, or one whose record was lost. Refusals never say whose a branch is.With
branch_creation = "webhook", a lost record can be restored.create_branchon an existing branch with no confirmed owner re-requests it from the receiver and records nothing until it answers. The receiver must answer 2xx only whenowner_subis the branch's registered owner, and refuse (409) anyone else. Withapi, keepstate_pathon a persistent volume, or a restart leaves every open branch unwritable here.
Proposals
Where the tenant's Forgejo is a staging copy of another forge, a separate
service turns a work branch into a pull request there; this server only asks
it, signed like the branch webhook (X-Alasin-Timestamp,
X-Alasin-Signature):
POST <proposals.url>with{"tenant", "repo", "branch", "title", "body"}, sent bypropose_changefor the branch's owner only. It answers 201{"pull_request", "commit", "owner_sub"}, 422{"refused": [...]}, or another status with{"error"}.POST <proposals.url>/statuswith{"tenant", "repo", "branch"}, read only, sent bychange_status. It answers 200{"proposed": false}or{"proposed": true, "pull_request", "number", "state", "draft", "head_sha", "review", "checks"}.
Every request carries a random nonce, so two identical requests in the
same second are still distinct for the receiver's replay check. A branch
that already has an open pull request gets 200 with that pull request
and created: false, because the push has already updated it. If the
answer is lost after sending, propose_change says to check
change_status before retrying. The secret must be at least 32 bytes, and
a shorter one is refused at load.
The service names the branch's owner from its own records, never from the
request. When it is down, propose_change fails with a message saying so,
and change_status still reports the build and the preview.
Tenant resolver
class TenantResolver(Protocol):
def resolve(self, principal: Principal) -> TenantConfig:
"""Return the tenant's settings, or raise UnknownTenant."""The default, StaticTenantResolver, serves the [[tenants]] from the config file. To
look tenants up elsewhere (a database, a control plane), implement the protocol and
pass it to alasin_mcp.app.from_config(cfg, resolver=...). The principal's tenant comes
from the verifier; the resolver decides what that tenant may reach.
Inbound verifiers implement:
class TokenVerifier(Protocol):
async def verify(self, token: str) -> Principal | None: ...Two ship: StaticTokenVerifier (fixed credentials, each bound to a tenant and subject,
compared by SHA-256 in constant time) and JwtVerifier (JWKS, issuer, audience, expiry;
the tenant from a configured claim).
Sessions and tracing
begin_change mints a work-session ID; every other tool requires it. Sessions expire
after server.session_ttl_seconds (default 12 h).
begin_change always starts a new trace, which becomes the work session's trace. If the
client sent _meta.traceparent (MCP SEP-414), its trace is recorded as a span link, not
adopted, so a client can't choose the Trace-Id stamped into commits. Later tool spans
are parented into the session's trace, so one work session is one trace. Incoming traces
on later calls are linked too. The session's trace ID goes into the Trace-Id trailer and
every audit event.
Spans are exported over OTLP/HTTP when telemetry.otlp_endpoint is set; export is off
by default. Trace IDs are generated either way.
Configuration
ALASIN_CONFIG names a TOML file (default /etc/alasin/config.toml). Secrets are never
written in it: every secret is referenced as <name>_file (a path) or <name>_env (an
environment variable name). See examples/config.toml.
Key | Default | Meaning |
|
| Bind address. |
|
|
|
|
| Proxies whose |
| (unset) | Header carrying the caller's address for audit events, e.g. |
|
| CIDRs of the peers whose |
|
| SQLite: sessions, encrypted tokens, OAuth state. |
|
|
|
| none | Base64 of 32 random bytes ( |
|
| Work-session lifetime. |
|
| OTLP/HTTP traces endpoint. |
| 8 MiB | Largest request body, checked before authentication. |
|
| |
|
| |
| The OAuth front door; see OAuth sign-in. | |
|
| |
| Per-person sign-in; see OAuth sign-in. | |
| Environment variables that set the identity provider instead of the table above (never both; | |
| (unset) | claude.ai managed authorization; see Managed sign-in under OAuth sign-in. The issuer (https) turns it on; the tenant is optional and needs the issuer. Environment only. |
| Lowercase tenant ID. | |
| Base URL of the tenant's Forgejo. | |
|
|
|
| The service account's Forgejo token (scopes | |
|
|
|
|
| Never written by the server. |
|
| If set, work branches must start with it. |
|
| See Auth modes. |
|
|
|
|
| The |
|
| Per tenant. |
| 1 MB, 50, 5 MB | Read and commit caps. |
|
| |
|
| |
|
| CI workflow folders; see Security model. |
|
|
|
|
| |
|
| Only a branch's creator may commit to it; see Branch creation. |
| off |
|
| off |
|
| off |
|
OAuth sign-in
With [auth.oauth], MCP clients that speak OAuth, such as claude.ai connectors, sign in
to this server directly; no gateway is needed. provider = "origo" runs
origo, an OAuth 2.1 + PKCE authorization server, in
this process. Install it with the extra: pip install 'alasin-mcp[origo]' (the image
includes it).
A request to
/mcpwithout a valid token gets a 401 whoseWWW-Authenticatenames the protected-resource metadata, so the client can discover where to sign in.The discovery and sign-in routes (
/.well-known/...,/authorize,/authorize/callback,/token,/register,/userinfo) are public; each checks its own credentials.Every token from the front door belongs to the one
tenantconfigured, which must useauth_mode = "service_account".The
oauth:subject prefix is reserved: an[[auth.static]]subject using it is refused, and a JWT whose subject starts with it is rejected.The
base_urlhost must be listed inserver.allowed_hosts, so the DNS-rebinding check covers the host clients sign in at.
Per-person sign-in ([auth.oauth.identity_provider]). origo sends each person to
the upstream OpenID Connect provider (Keycloak, say) to sign in, and its tokens then
carry that person: origo's sub (<issuer>|<IdP sub>), the email only if the IdP
verified it, the name and the groups. The MCP client is still one pre-registered
[[auth.oauth.clients]] entry, such as a claude.ai connector.
The principal's subject is
oauth:<issuer>|<IdP sub>. Work sessions and branches belong to the person, not to the client. A token that names no person, or a person of another issuer, is refused.The lane gate: origo checks
allowed_groupsat sign-in, and this server checks it again on every write tool (create_branch,commit_files) against the groups in the token used. Reads stay open to anyone who signed in. A write also needs a name and a verified email on the token, and a principal from the identity provider: a credential that asserts its own groups can't write.With
recheck_on_refresh = true(recommended), every refresh first refreshes at the IdP and re-appliesallowed_groupsto the fresh groups. A disabled account, an ended or revoked IdP session (Keycloak: SSO Session Idle/Max, Client Session Idle/Max) or a removed group ends the grant within one access-token lifetime (token_ttl_seconds), whatever the client holds;max_grant_age_secondsstays an outer cap. Grants from before it was turned on need one new sign-in.With
offline_access = trueas well (it requiresrecheck_on_refresh), origo also asks the IdP for theoffline_accessscope, so the IdP refresh token it keeps is an offline one: the grant follows the IdP's offline session (Keycloak: Offline Session Idle/Max) instead of the browser SSO session, and a person stays signed in while they keep using the connector. Every refresh is still checked at the IdP, so signing out, a disabled account, a removed group or a revoked offline session still ends the grant within one access-token lifetime. origo's own refresh tokens rotate on every refresh, sorefresh_token_ttl_secondsis an idle limit; set it andmax_grant_age_secondsat least as long as the IdP's offline limits, or they end the grant first. At Keycloak, the client needs theoffline_accessclient scope (a realm default) and the person theoffline_accessrole (in the realm's default roles). An unreadabletoken_key_filesentry stops the server at start-up.Without it, groups are those of the sign-in: a refresh doesn't ask the IdP, so a person removed at the IdP keeps access until the grant reaches
max_grant_age_seconds, plus at most one access-token lifetime. MCP clients such as claude.ai don't re-sign-in silently once refresh is refused, so a shortmax_grant_age_secondsmeans a manual reconnect that often.Commits are authored by the person (their verified name and email) and committed by the Forgejo service account.
The config refuses an inconsistent tenant: it needs
author_source = "token_claims"andbranch_owners = true, may have no[[auth.static]]credentials (they are shared accounts),public_registrationcan't be on (list connector platforms incimd_allowed_clientsinstead), and[auth.jwt]can't be configured at all (a JWT's tenant comes from a claim, so it could reach this tenant).Commit messages can't carry
Co-authored-byorSigned-off-bytrailers (except the configuredagent_coauthor, which the server adds anyway): the commit is attributed to the signed-in person and nobody else. This applies to every tenant.Register the callback
<base_url>/authorize/callbackat the IdP as the client's only redirect URI. For Keycloak, add a Group Membership mapper with Add to ID token on, and writeallowed_groupsexactly as it emits them:/namewith Full group path on,namewith it off.
Managed sign-in (claude.ai managed authorization). With
ALASIN_MANAGED_SIGNIN_ISSUER set, origo also accepts the RFC 7523 jwt-bearer grant
(urn:ietf:params:oauth:grant-type:jwt-bearer) at /token with an Identity Assertion
JWT Authorization Grant (ID-JAG): claude.ai connects every member of the organization
without a browser sign-in. Unset, /token refuses the grant (unsupported_grant_type)
and the metadata doesn't advertise it.
ALASIN_MANAGED_SIGNIN_ISSUER: the Issuer URL claude.ai's managed-authorization page shows for "Claude-issued" (https://identity.anthropic.com/issuers/iss_...), one per organization.ALASIN_MANAGED_SIGNIN_TENANT(optional): the Tenant ID entered there; the assertion'saud_tenantmust then equal it.It needs the identity provider and
cimd_allowed_clients(only those clients may present an assertion); start-up refuses it without either, a tenant without an issuer, or a non-https issuer.The assertion only names an email. The token is for the one enabled IdP user with that verified email, with the same subject, groups and
allowed_groupsgate as an interactive sign-in; no such user meansinvalid_grant. origo looks the person up with the identity provider's own client (client credentials), so for Keycloak that client needs Service accounts enabled and the realm-management role view-users.Groups are emitted as names (origo's
group_paths=False): the Keycloak group mapper's Full group path must be off, asallowed_groupsassumes.No refresh token: claude.ai fetches a fresh assertion, so someone removed from the organization or disabled in the IdP stops within one access-token lifetime.
Each exchange is audited as
action = "managed_sign_in", attempt then outcome, like a sign-in.
Approve-only (no identity provider). origo then signs in nobody: whoever opens the
authorize URL can approve, and the subject is the OAuth client, oauth:<client id>,
shared by everyone who signs in through it. origo refuses every authorization in this
mode unless allow_unauthenticated_consent = true. The setting is passed to origo
explicitly, so its ORIGO_ALLOW_UNAUTHENTICATED_CONSENT environment variable has no
effect here. [[auth.static]] and [auth.jwt] work beside it on the same /mcp.
Warning:
public_registrationlets anyone on the internet connect. With it on, any client that can reach this server registers itself at/registerand gets a token for the tenant: origo checks no user. It is refused unless the config also setspublic_registration_i_understand_anyone_can_connect = true. Leave it off and list each client under[[auth.oauth.clients]], unless something in front of this server (a network policy, an access proxy) already limits who can reach it.
Another OAuth or OIDC issuer can be added as a further front door (oauth.py): its
verifier is a JwtVerifier against the issuer's JWKS.
Running
docker build -t alasin-mcp .
docker run -p 8000:8000 \
-v ./config.toml:/etc/alasin/config.toml:ro \
-v ./secrets:/run/secrets:ro \
-v alasin-state:/var/lib/alasin \
alasin-mcpBehind an OAuth gateway: the gateway authenticates the user, then forwards /mcp to this
server with Authorization: Bearer <the static credential>. /healthz is public, as is
/oauth/forgejo/callback (used only by user-delegated tenants). Point allowed_hosts at
the host name the gateway uses for this upstream.
The Forgejo service account needs write access to the lane repositories and nothing more: not an admin, not an organisation owner. Put branch protection on the default branch, and protected file patterns on work branches for anything the agent must not change.
Development
uv sync
uv run ruff check . && uv run ruff format --check . && uv run pyright
uv run pytest tests/test_units.py tests/test_cross_tenant.py # no Docker needed
uv run pytest tests/test_integration.py # starts Forgejo in DockerThe integration tests start a pinned Forgejo image (tests/forgejo.py) with a 512 MB
memory cap and tear it down afterwards. Every test has a timeout. CI sets
ALASIN_REQUIRE_FORGEJO=1, which turns a missing Docker into a failure instead of a skip.
Source files carry an SPDX-License-Identifier: Apache-2.0 header
(scripts/check_spdx.py checks it).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Multi-tenant backend your coding agent configures over MCP: auth, RBAC, data, workflows, deploy.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server that enables AI assistants to read, create, and manage issues, repositories, and releases on Gitea, Forgejo, or Codeberg instances via personal access tokens.21117 PyPI2MIT
- AlicenseBqualityCmaintenanceA Model Context Protocol (MCP) server for Forgejo and Gitea instances, enabling AI assistants to interact with repositories, issues, pull requests, and more.10017MIT
- AlicenseNot gradedqualityDmaintenanceA secure and scalable Git MCP server giving AI agents powerful version control for local and (soon) serverless environments.Apache 2.0
- AlicenseCqualityDmaintenanceA policy-aware MCP server for GitHub and GitHub Actions that enables safe AI-assisted infrastructure workflows—inspecting repositories, preparing branches and pull requests, and constrained remote mutations behind explicit preview-bound approval tokens.18MIT