Agents
MCP server
Connect Claude Code, Codex, opencode, or any MCP client to your instance so an agent can work in Nexul with your permissions.
Every Nexul instance has an MCP server at /mcp. Connect your agent tool to it and the agent can read docs, file tickets, post in chat, deploy stacks, and everything else in the table below, acting as you, with your permissions and nothing more.
A paired computer needs none of this: its setup connects every provider for you, with the computer’s own token. Follow these steps for any other tool or machine.
Connect
- Open Settings → Security and create a token under Personal access tokens. Copy it now; the raw token (
dep_…) is shown once. - Add the server to your tool, with your instance’s URL and the token.
Claude Code, in the top-level mcpServers object of ~/.claude.json (your user scope, every project):
{
"mcpServers": {
"nexul": {
"type": "http",
"url": "https://nexul.example.com/mcp",
"headers": { "Authorization": "Bearer dep_your_token_here" }
}
}
}For one project, use .mcp.json in its root. That file is usually committed, so keep the token out of it: Claude Code expands ${VAR} in headers, so set NEXUL_TOKEN in your shell and write the header as "Authorization": "Bearer ${NEXUL_TOKEN}".
A client that starts the server through mcp-remote takes the token from its environment, so it never shows in the process list:
{
"mcpServers": {
"nexul": {
"command": "npx",
"args": ["mcp-remote", "https://nexul.example.com/mcp", "--header", "Authorization:${NEXUL_AUTH}"],
"env": { "NEXUL_AUTH": "Bearer dep_your_token_here" }
}
}
}Never put a token in a command’s arguments, such as claude mcp add --header or a literal --header for mcp-remote: any local user can read it with ps, and your shell history keeps it.
opencode, in opencode.json:
{
"mcp": {
"nexul": {
"type": "remote",
"url": "https://nexul.example.com/mcp",
"headers": { "Authorization": "Bearer dep_your_token_here" },
"enabled": true
}
}
}Codex, in ~/.codex/config.toml:
[mcp_servers.nexul]
url = "https://nexul.example.com/mcp"
http_headers = { Authorization = "Bearer dep_your_token_here" }A missing or wrong token gets 401. Revoke the token in the same place to cut the agent off.
What an agent can do
112 tools, each named <object>_<verb> and shaped around a task rather than a button.
| Area | Tools |
|---|---|
| Workspaces and projects | workspace_list, workspace_update, project_list, project_get, project_create, project_update, project_delete |
| Tickets | ticket_list, ticket_get, ticket_create, ticket_update, ticket_delete, ticket_test_report |
| Docs | doc_list, doc_get, doc_create, doc_update, doc_delete |
| Memories | memory_list, memory_get, memory_create, memory_update, memory_delete |
| Attachments | attachment_create, attachment_get |
| Templates | template_get, template_update |
| Chat and notifications | conversation_list, conversation_update, conversation_delete, message_list, message_post, mention_search, notification_list, notification_update |
| Bots | botwebhook_list, botwebhook_create, botwebhook_update |
| Calendar | meeting_list, meeting_create, meeting_update |
| Stacks and deploys | stack_list, stack_get, stack_create, stack_update, stack_delete, stack_deploy, deploy_list, deploy_cancel |
| Machines and the instance | machine_list, machine_discover, machine_import, host_create, host_delete, instance_get, instance_update, instance_upgrade |
| DNS and routing | dns_zone_list, dns_record_list, dns_record_create, dns_record_update, dns_record_delete, dns_tunnel_list, dns_tunnel_create, dns_tunnel_update, dns_tunnel_delete, gateway_list, gateway_create, gateway_delete, exposure_list, exposure_create, exposure_delete |
| Topology | topology_get, topology_update |
| Repositories and pull requests | repository_list, repository_scan, pull_request_list, pull_request_get |
| Plays | play_list, play_create, play_update, play_delete, play_run, trail_list, trail_update |
| Automations | automation_list, automation_create, automation_update, automation_delete, automation_token_create |
| Paired computers and skills | computer_list, computer_create, computer_pair, computer_delete, computer_project_create, computer_setup_run, computer_setup_update, computer_mcp_token_create, computer_mcp_token_delete, skill_get |
| Accounts and access | account_get, account_list, account_update, account_delete, invitation_create, invitation_list, invitation_delete, permission_overwrite_list, permission_overwrite_update, role_update, role_delete |
| Failed events | dead_letter_list, dead_letter_replay |
A few things that save an agent a wasted call:
- Updates are patches. Send only the fields to change; the rest keep their values.
- Edit a body without resending it.
doc_update,ticket_update,play_update, andmemory_updatetakeedits, a list offindandreplacepairs applied in order to the body (a ticket’s description, a play’s instructions) asdoc_get,ticket_get,play_list, andmemory_getreturn it. Eachfindmust match exactly once; if any fails, nothing is saved.editsdoes not go with the whole body field orrevert_to_version, and the result is one saved version. - Lists page. They take
limit(50 by default, 100 at most) andoffsetand returnitems,total,has_more, andnext_offset.totalcounts everything you can see, searches included, so paging withnext_offsetreaches every match. A row added ahead of your place while you page shifts the later pages by one. - A list given an id returns that one record.
deploy_listwith a deploy’sidreturns it with its log;trail_list,automation_list,computer_list, anddns_tunnel_listwork the same way. A field’s description lists the values it takes. - Tickets by key. Ticket tools take an id or a key such as
WEB-12. A key is unique only within a workspace, so when you hold it in two, passworkspacetoo, or the call is refused with the workspaces to choose from. meis you. A ticket’sdeveloperandtesteronticket_createandticket_update, and thedeveloperfilter onticket_list, takemefor the person the connection acts as, so an agent need not look its own login up first. An automation token is no member, so it cannot useme.- Change many tickets in one call.
ticket_updatetakesids, up to 100 ids or keys, and applies the same fields to each, such as adeveloperor acategory_id. Every ticket is found before any changes, so a mistyped key changes nothing; the tickets then change in order, and the call stops at the first one that fails and names the ones already changed.title,body,edits,position, andrevert_to_versionchange one ticket at a time.ticket_createtakestickets, up to 100 titles and bodies that share every other field, such as a doc split into tickets of one type and category; it creates them in order, stops at the first that fails, and returns their keys.ticket_listfinds the tickets to pass, filtered bycategory_id(an empty string for uncategorized),status_id, ordeveloper(a login, or an empty string for unassigned). - Errors say how to fix the call. A failed tool returns the fields it needs, not a bare error. A refused one names the role or rule that refused it;
permission_overwrite_listwith auser_idexplains every answer on a doc, folder, stack, play, project, or instance area. - Read-only and destructive hints. Reads are marked read-only, and deletes and anything that starts work are marked destructive, so your client knows what to confirm.
- Not found can mean no access. Someone who sees only some projects gets not found for the rest, and so does their agent.
- Changes are audited. Every call to a tool that changes something is recorded in the audit log under your name and kept for 45 days. Reads are not.
Some tools worth knowing:
pull_request_getanswers “why does this code exist”. Give it a repository and a pull request number, or a commit SHA fromgit blame, and it returns the pull request, its tickets, each ticket’s doc, bugs found after done, and the decisions-log entries citing them.attachment_createputs a file on a doc, ticket, conversation, or memory, up to 10 MiB, and returns a markdown line to embed it.attachment_getreads one back; an image comes back as an image.ticket_getincludes the ticket’s test target, andticket_test_reportpasses or fails it like the Pass and Fail buttons.instance_getwith alogsobject also reads the instance’s own logs, newest first. It needslogs:readbesidesinstance:read.instance_getalso returns the instance’s enterprise license, andinstance_updatewithlicense_keypastes or removes the key. With the single sign-on settings,instance_getalso returns them andinstance_updatetakes anssoobject. Withbranding,instance_updatesets the instance’s own look.play_runstarts a play on your paired computer.computer_createadds one of your computers and returns the command that installs its runner:commands.unixfor Linux and macOS,curl -fsSL https://nexul.io/computer.sh | sudo sh -s -- <token>, andcommands.windowsfor Windows,& ([scriptblock]::Create((irm https://nexul.io/computer.ps1))) <token>, where the token is good once, for an hour, and only on your instance. Run it on that computer from your own account: on Linux and macOSsudoonly places thenexul-computersystem service (a LaunchDaemon on a Mac), which runs the runner as you, never as root; on Windows it needs no administrator and installs a task of yours that runs the runner while you’re logged on. Either installs T3 Code when it’s missing (what it installs). Once the runner connects,computer_listshowsrunner.connectedon the computer; a computer added without a name takes its hostname. Passidinstead for a fresh command when the last one expired, or to move a computer paired through a tunnel or by URL to the Nexul app: once it pairs through its runner it keeps its links, setup, MCP token and trails, and only then are its tunnel, DNS record and Access app deleted;sudo cloudflared service uninstallon the computer removescloudflaredafterwards. A failed move leaves the computer working as it was. Only you can see or use your computers; anyone else, a workspace Owner included, gets not found.- Once its runner connects and T3 Code answers there, the computer pairs on its own, and pairs again before its 30-day session ends.
computer_pairwith only the computer’sidpairs it again now, and moves a computer whose runnercomputer_createwith itsidinstalled. A failed pairing leaves the computer as it was, andcomputer_listsays why inpair_error.computer_listalso returns a computer’sfactsonce its runner reports (its system, git identity, whether it can sign in to GitHub, free disk, Docker, T3 Code’s state and port, and the providers and projects T3 Code lists) withfacts_at, when they last changed; only you get them. With one computer’sid, a computer whose facts show Docker available also lists itscontainers, andcontainer_logs: {container, tail}adds that container’s last lines (200 by default, at most 1000), read live through the computer’s runner.runner_logs: {lines}adds the last lines the computer’s Nexul app itself logged, the same way. A person the computer is shared with bycomputers:read_logsgets both reads and the container list too, with each container’s own environment values hidden. computer_pairwithposition,runs_at_onceorchat_project_idchanges the computer’s settings instead of pairing it: its place in your order (0 for first), how many play runs it takes at a time (1 to 5), or the T3 project chats outside any project run in.computer_listreturns each computer’sposition,runs_at_once,chat_project_id, andrunning, the play runs going on it now. Your defaults and a project’s own computers are set on the Computers settings page.computer_project_createadds a new T3 project to one of your computers, for whencomputer_listshows none holding the work. Giverepository(owner/name) to clone a GitHub repository, ornameto make an empty folder (setup makes one callednexul-chatby itself on a computer with no T3 project at all). It lands in the folder most of the computer’s T3 projects share, or~/Codewhen it has none, and the computer’s Nexul app clones with a read-only token for that one repository, so the computer needs no GitHub sign-in (an older app falls back to the computer’s own git credentials). It returns the project’s id, thet3_project_idplay_runtakes, once the clone is done; a failed clone leaves no project behind and says why, such as the computer having no GitHub sign-in. A computer paired before cloning existed refuses with a message to pair it again, whichcomputer_pairor Pair again on the Computers settings page does.
The server also offers resources (docs://{id}, tickets://{id}, and topology://{id} for a workspace’s canvas) and four prompts: create_ticket_from_doc, deploy_and_watch_stack, investigate_failure, and ship_repository, which runs the project wizard’s steps end to end.
Work an agent starts is recorded as yours, marked as started over MCP. Nexul hides any dep_ token as [redacted token] before it saves a play’s trail or an agent’s reply.
Protocol
The server runs on the official MCP Go SDK over Streamable HTTP, statelessly: each POST /mcp gets one JSON response, with no sessions or open streams. A browser request is accepted only from your instance’s own URL.