Hinatadocs

MCP server (AI)

Hinata speaks the Model Context Protocol (MCP), the open standard for AI clients. Connect Claude (desktop, web or Claude Code), Cursor or any other spec-compliant client.

The client can then search and create issues, read and write the knowledge base, and log work. It always has exactly the permissions of the connected user.

Where it lives

The MCP server is built into the Hinata backend, with no sidecar and no second deployment. It is served at /mcp on the same host as the API. Every tool call runs through the same service layer as a normal request, with the same rules for team and project membership and article visibility.

How it authenticates: Personal Access Tokens

An AI client connects with a Personal Access Token (PAT) you create in the app. A PAT is:

  • Scoped. You grant only the capabilities it needs (issues:read/write, projects:read/write, boards:read, sprints:write, teams:read, users:read, kb:read/write, worklog:read/write, search:read, notifications:read, shifts:read/write/plan). A read-only token can never write.
  • Revocable. Any time. The next request with that token is rejected immediately.
  • Hashed at rest. Only a SHA-256 hash is stored. You see the plaintext once, at creation.
  • Confined to /mcp. The regular REST API rejects PATs, so a scoped token can never become full account access.

Copy the token when you create it

The full token (prefixed hn_pat_…) is shown only at creation. Put it in your client's config right away. Later you can only revoke it and create a new one.

Create a token

  1. In the app, open Account → Access tokens.
  2. Choose New token and give it a name (e.g. Claude Desktop).
  3. Select the scopes it needs and an optional expiry.
  4. Copy the generated token.

Feature flag

Access tokens appear only when the MCP feature is enabled. Admins turn it on under Admin area → MCP and cap how many tokens each user may hold.

Connect a client

There are two ways to connect, depending on the client.

One-click connect (OAuth 2.1)

For Claude.ai and Claude Desktop, add Hinata as a custom connector with the MCP URL https://YOUR-HINATA-HOST/mcp and press Connect.

Hinata is a full OAuth 2.1 authorization server:

  • The client discovers the server through metadata (RFC 9728 / RFC 8414).
  • It registers itself (Dynamic Client Registration).
  • A browser opens. You sign in to Hinata as usual (password, 2FA or SSO) and approve the requested scopes.

There is no token to copy. Access runs on a short-lived token with a rotating refresh token, both revocable.

OAuth needs HTTPS

Your server must be reachable over HTTPS at a public URL (its base-url). OAuth is on by default. Admins can turn it off, or turn off open client registration, under Admin area → MCP.

Bearer token (PAT)

For Claude Code, Cursor and scripts, use a Personal Access Token:

claude mcp add --transport http hinata https://YOUR-HINATA-HOST/mcp \
  --header "Authorization: Bearer hn_pat_your_token_here"

Any client that supports remote MCP over Streamable HTTP works the same way: point it at https://YOUR-HINATA-HOST/mcp and send the token as an Authorization: Bearer header.

What the AI can do

The server offers a fixed, curated set of tools. There is no way to call arbitrary endpoints, and no admin, auth or setup operations.

Every tool carries the MCP annotations readOnlyHint and destructiveHint. Clients like Claude use them to tell read tools apart from writes and deletions.

Read tools:

ToolScopeWhat it does
search_issuesissues:readFilter issues by project, state, assignee, sprint, backlog, type or text
list_my_issuesissues:readIssues assigned to the connected user
get_issueissues:readOne issue by id or readable id (e.g. ASTA-42)
get_issue_hierarchyissues:readAn issue's epic or parent and sub-tasks
list_commentsissues:readAn issue's comments, paginated
list_attachmentsissues:readAn issue's attachment metadata (name, type, size)
get_dev_infoissues:readLinked branches, commits, pull requests and builds of an issue
list_projects / get_projectprojects:readProjects visible to the user, incl. workflow states and labels
list_project_membersprojects:readA project's members, to resolve people to assignee ids
get_project_metricsprojects:readIssue counts: total, resolved, open, per workflow state
copy_projectprojects:writeCopy a project with its plan; needs project templates
set_issue_deadlineissues:writeKeep a deadline as an offset from the project's date; needs project templates
list_boards / get_boardboards:readAgile boards the user can open, with columns, WIP limits and active sprint
list_sprintsboards:readA board's sprints, incl. archived on request
get_sprint_reportboards:readSprint insights: burndown, velocity, scope changes, assignee load
list_teams / get_teamteams:readThe user's teams, incl. members and their roles
search_usersusers:readDirectory search by name, username or title
get_meusers:readThe connected user's own profile
searchsearch:readGlobal search across issues, projects, people, boards, docs
read_kb_articlekb:readA knowledge base article's content, respecting its visibility
list_kb_articleskb:readVisible knowledge base articles, by project or space
list_work_itemsworklog:readThe logged time on an issue
my_timesheetworklog:readThe user's own logged time in a date range
list_my_work_itemsworklog:readThe user's own time entries in a date range, paginated, optionally by project or text
time_summaryworklog:readThe user's own time in up to 366 days, totalled and grouped by project, issue, activity, tag, day, week or month
get_timerworklog:readThe user's running timer, if one runs
my_time_off_balanceworklog:readThe user's own leave per absence type: entitled, taken, planned, left. Sick leave is not listed
list_my_notificationsnotifications:readThe user's notification inbox plus unread count

Write tools:

ToolScopeWhat it does
create_issue / update_issueissues:writeCreate an issue, update fields incl. state, sprint, parent, assignees
add_comment / edit_comment / delete_commentissues:writeComment on an issue, edit or delete your own comment
add_participant / remove_participantissues:writeShare an issue with a person outside its project or end the share (Sharing an issue)
create_sprint / update_sprintsprints:writePlan a sprint on a SCRUM board, adjust name, goal, dates, capacity
start_sprint / complete_sprintsprints:writeStart and complete a sprint. Completing moves open issues
create_kb_article / update_kb_article / delete_kb_articlekb:writeManage knowledge base articles (visibility can never be changed via MCP)
log_work / delete_work_itemworklog:writeLog time against an issue, delete your own work item
update_work_itemworklog:writeChange your own time entry; locked days, submitted periods and invoiced entries are refused with the reason
start_timer / stop_timer / discard_timerworklog:writeStart a timer, stop it into a time entry, or throw it away
request_time_offworklog:writeAsk for time off; it goes to whoever decides it, as from the app

The timer, entry and absence tools need the extended time tracking (and absence management for the last two); with the module off they say so and the four older tools keep working. No tool reads anybody else's time or balance, and no tool decides a leave request: approving stays with a person in the app. Sick leave is neither reported nor read over MCP.

There are also resources for direct reference (hinata://issue/{ASTA-42}, hinata://project/{KEY}, hinata://kb/{id}, and your own hinata://time/timer, hinata://time/entries/{id} and hinata://time-off/balance) and a few prompt templates (triage an issue, draft a sprint stand-up).

Shifts

With shift planning switched on, an assistant can answer questions like these and act for you:

  • "When is my next shift?"
  • "Where are people still missing on Saturday?"
  • "Sign me up for setting up on Friday."
  • "Withdraw me from my shift on Sunday."
ToolScopeWhat it does
list_my_shiftsshifts:readYour own shifts and waiting-list places in a period, the next 30 days by default
next_shiftshifts:readYour next own shift, or that there is none
list_shift_eventsshifts:readEvents with numbers: needed, taken, shifts still short. Optionally only events where people are missing
get_shift_eventshifts:readOne event with all its shifts as numbers, without names
get_shiftshifts:readOne shift with the people who hold a place. People on the waiting list are counted, never named
self_assign_shiftshifts:writeSign yourself up. On a full shift you join the waiting list, and the answer says so
release_shiftshifts:writeWithdraw from your own shift or leave the waiting list
confirm_shift / decline_shiftshifts:writeConfirm or decline an assignment
assign_shift / remove_assignmentshifts:planAs a planner, put somebody on a shift or take them off

A period covers at most 62 days and a page at most 100 entries. Times come as wall-clock times in the event's time zone, with the zone named. Hinata refuses an overlap with one of your own shifts in a sentence that gives the reason.

shifts:plan is meant for tokens that work on behalf of a planner. The one-click connection leaves it out when the client names no scopes; a client only gets it by asking for it explicitly and with your approval. The three shift scopes appear in the app and on the approval page only while shift planning is switched on. While it is off, the tools answer that the feature is not enabled.

Event texts are not instructions

People write the title, location and description of an event, and an assistant reads them. If one says something like "Ignore all previous instructions", that is text, not a command. Hinata passes these texts in their own data fields and never in a tool's description. Still, give a token only the scopes it needs, and do not let an assistant with shifts:plan assign anybody without asking you first.

Sign-ups through MCP are recorded in the audit log as assignments, just like in the app. The extra records saying that a token acted (MCP_SHIFT_*) stay off until an administrator switches them on.

Security model

  • The ACL is never bypassed. Every tool resolves the connected user and goes through the same services as the app. Team and project membership and article visibility apply as in the UI.
  • Scopes gate writes and reads. A token without the required scope is refused before anything happens.
  • PATs are /mcp-only, hashed at rest, revocable and can expire.
  • Everything is rate-limited on its own per-IP budget. Every write, every token creation or revocation and every OAuth authorization is recorded in the audit log. Starting, stopping and discarding a timer is the exception: like the same actions in the app, those records are off until an administrator switches them on, because a line per start and stop is a record of when somebody worked.
  • OAuth follows the standard and is hardened: OAuth 2.1 with mandatory PKCE (S256), exact redirect URI matching, single-use authorization codes, hashed and rotating refresh tokens, and audience-bound access tokens (RFC 8707). OAuth tokens carry the same scopes and go through the same tools and ACLs as PATs.