Connect your coding agent

Any coding agent or harness that speaks the Model Context Protocol can connect to Neens. You add one server URL, your client opens a browser to sign in to Neens, you pick an agent, and the client is then authorized as you: every tool call it makes is attributable to your account and limited by your role, and you can revoke it at any time.

At a glance


Server URL	`https://app.neens.ai/mcp` (self-hosted: `https://<your-neens-host>/mcp`)
Transport	MCP Streamable HTTP, `POST /mcp`, stateless
Sign-in	A browser window to Neens — password or SSO
Authorized as	You — your account and role, on the one agent you pick
Manage	Settings → MCP access — see and revoke every connection
Headless / CI	Not over MCP — use the REST API or the pre-prod CLI with an agent key

There is no key to paste. The Neens MCP server rejects a bare agent API key (nk_live_…) with 401 and asks the client to sign in a person instead. A key names an agent but no person; the browser sign-in binds the connection to you, so what your coding agent can do is exactly what you can do in that agent.

Add the server

Pick your client. Each tab adds the same server; only the configuration syntax differs.

Run this in your terminal:

claude mcp add --transport http neens https://app.neens.ai/mcp

The first time Claude Code uses the server it opens your browser to sign in. To sign in again later, or to check the connection, run /mcp inside a Claude Code session. Tools appear as mcp__neens__<tool>.

Add the server, then sign in:

codex mcp add neens --url https://app.neens.ai/mcp
codex mcp login neens

Or add it to ~/.codex/config.toml by hand:

~/.codex/config.toml

[mcp_servers.neens]
url = "https://app.neens.ai/mcp"

codex mcp login neens opens your browser; Codex receives the result on a local loopback callback (http://127.0.0.1/…).

Add a neens entry to .cursor/mcp.json in your project (or ~/.cursor/mcp.json to make it available in every project):

.cursor/mcp.json

{
  "mcpServers": {
    "neens": { "url": "https://app.neens.ai/mcp" }
  }
}

Cursor starts the sign-in from its MCP settings. Neens accepts both of Cursor’s OAuth callbacks: the desktop app’s http://localhost:8787/callback and the one cloud agents use, https://www.cursor.com/agents/mcp/oauth/callback.

Add a neens server to .vscode/mcp.json in your workspace:

.vscode/mcp.json

{
  "servers": {
    "neens": { "type": "http", "url": "https://app.neens.ai/mcp" }
  }
}

VS Code runs the sign-in in your browser the first time it starts the server.

Any client that supports remote MCP servers with OAuth can connect. What it needs to know:


Endpoint	`POST https://app.neens.ai/mcp` — Streamable HTTP, JSON-RPC 2.0, stateless
Authorization	OAuth 2.1 authorization code + PKCE (`S256`), public clients
Client registration	Dynamic, at `/oauth/register`
Discovery	`/.well-known/oauth-protected-resource` (RFC 9728) and `/.well-known/oauth-authorization-server` (RFC 8414)
Scopes	`mcp:read`, `mcp:write`
Refresh	Refresh tokens are issued and rotate on every use
Redirect URIs	`https` URLs, or `http` on a loopback host (`127.0.0.1`, `::1`, `localhost`)

An unauthenticated request to /mcp returns 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource". That header is what starts a compliant client’s sign-in.

Self-hosted Neens? Replace https://app.neens.ai with your own Neens URL in every snippet. Nothing else changes.

Your client opens a browser window to Neens. Enter your work email: if your company uses single sign-on, Neens sends you straight to your identity provider, including whatever MFA it enforces, and you never enter a separate Neens password. Otherwise you sign in with your Neens password as usual.

Pick an agent and allow

Neens shows a short consent screen with a picker for which of your agents this connection may use. Choose the agent and click Allow. The browser hands control back to your client.

The consent screen shows Requested by (the name the client registered itself with) and Returns to (the host it will hand you back to; for a desktop client, this computer). A client chooses its own name, so check the return host too: if it isn’t the client you just started, click Deny.

Verify

Ask your coding agent which Neens agent it is connected to. It calls get_current_project and answers with the agent, organization and company names. Listing the tools should show the Neens MCP tools.

A connection is scoped to the one agent you picked: it can read and write within that agent and nothing else, and it can never delete. To work in a second agent, add the server again under a different name (for example neens-staging) and pick that agent during its sign-in.

Neens brokers the sign-in; it never hands your client an identity-provider token. Your IdP authenticates you, and Neens then issues your client its own short-lived token bound to you, your role and the agent you picked.

Staying connected

The access token is short-lived, but your client refreshes it in the background with a longer-lived refresh token, so a working connection keeps working through a day of use. When the refresh window ends, or the connection is revoked, the next tool call fails with a request to sign in again. Re-run your client’s sign-in (/mcp in Claude Code, codex mcp login neens in Codex, or the sign-in prompt in your client’s MCP settings) and it reconnects.

Manage your MCP access

Every connection you approve is listed under Settings → MCP access, in Active MCP connections: the client, the agent it is scoped to, and when it was created, last used and expires.

Revoke a connection to disconnect it immediately. Its next tool call is rejected and it has to sign in again.
The list shows your own connections only. Revoking one never affects anyone else’s.
Connections drop off the list when they expire; revoking ends one early.

⚠️

Revoke any connection you don’t recognize, the same way you would revoke any credential. Because the connection is bound to your account, a revoke is complete: there is no shared key left that keeps working.

Headless and CI

MCP in Neens is for a person working through a coding agent. There is no way to mint an MCP token by hand, and an agent API key is not accepted on /mcp. For automation with no person to sign in, use an agent API key (nk_live_…, from Settings → API keys) with:

The pre-prod CLI, neens eval run, to gate a release in CI — see Pre-prod evaluations → In CI.
The REST API, which the MCP tools call under the hood — see the API reference.

Troubleshooting

Symptom	Cause	Fix
The client keeps asking you to sign in, or reports `401` on every call	The sign-in never finished, the connection expired, or it was revoked	Run your client’s sign-in again and complete it through Allow. If it loops, remove the server, add it again and sign in
`401` with “This MCP server requires user authentication”	The client is sending an agent API key instead of signing in	Remove any `Authorization` header or `nk_live_` key from the client’s config and let it run the browser sign-in
Tools work but show the wrong data	You picked a different agent at the consent screen	Ask for `get_current_project` to confirm. To switch, revoke the connection under Settings → MCP access and sign in again, picking the right agent
No Neens tools are listed	The client didn’t reload its MCP config, or sign-in didn’t complete	Restart the client session, then check its MCP status (`/mcp` in Claude Code, `codex mcp list` in Codex, MCP settings in Cursor and VS Code)
A write is refused with `403`	Your role doesn’t allow that write in this agent	Ask an admin for the role, or do it in the app with an account that has it
The browser shows “You don’t have access to any agents yet”	Your account has no agent membership	Ask an admin to add you to an agent, then sign in again

Coding agents overview — what your coding agent can do with Neens.
Skills — teach your coding agent how to run the loop.
MCP tools — every tool, with walkthroughs.
Single sign-on (SSO) — the sign-in used when your company federates login.
API keys — agent keys for scripts and CI.

Overview Skills