Connecting from Claude / ChatGPT (MCP)
Endpoint
https://<ホスト>/mcp/<テナント ID>
One connector per tenant. The tenant is not baked into the access token but named by the URL path, so leaving, a role change, or a tenant suspension takes effect immediately.
Paste this URL as is into the connector settings of the MCP client (Claude / ChatGPT / others).
To copy it from the screen, use the 「外部の AI から使う」 tab of /settings/connections.
Both new and old protocol versions work. It speaks both 2026-07-28 and the 2025 generation, so client-side support does not matter.
Signing in
On the first connection a browser opens; sign in to Samurai App and grant permission. No secret key is stored on the client side (PKCE), so the URL is all you paste.
Once connected, that client can read Samurai App's business data.
What it can do
One tool per resource, with the operation chosen by action. It does not mirror the REST endpoints
1:1 because that would exceed 80 tools and make the list unusable in any client.
There are 21 resources, the same as the CLI (conversation approval knowledge database siroe calendar meeting memory
skill bot app file trigger workflow approver tenant setting secret connection
audit activity).
Tool names are samuraiapp_<資源名> (samuraiapp_conversation, etc.). They appear with this
spelling in the client's tool list.
Groups (departments) are in samuraiapp_tenant. Look up the target ID here when setting a resource's
visibility to 「グループ」.
siroe pages, including the canvas, are samuraiapp_siroe. Find a page id with list_pages or search,
read the body with read_blocks and the canvas with read_elements, then write with add_block / add_element
and friends. update_* needs the version the read returned. Password blocks are not readable or editable from outside AI —
read_blocks returns them with empty attributes, and adding, changing, or deleting one is refused (a person opens and edits
them on screen). Comments, tags, saved rules and the trash stay on the screen.
Calendar events are samuraiapp_calendar and meetings are samuraiapp_meeting. Times are ISO 8601, read as Japan
time without an offset. Create a call with samuraiapp_meeting create, put it on an event with create_event and
link_meeting, and read what was said with transcript. create_event and update_event take groups (names or ids, expanded to
the members at that moment — later membership changes are not followed) and guests (outside email addresses; Samurai
App sends them nothing, the invitation comes from Google Calendar or Outlook when export is on). Writes run with your own rights, without an approval card;
delete_event and end are marked destructive. A repeating event comes back from list_events once per occurrence,
all with the same id and each with its own occurrence: pass that occurrence to delete_event to remove only that
one — without it the whole series is deleted. update_event on a repeating event changes every occurrence. Events
imported from Google Calendar or Outlook carry importedFrom and cannot be changed or deleted here — change them in
that calendar. Webinars, in-person recording, guest links, who can see a meeting, making an event repeat, and exporting
to or importing from an outside calendar stay on the screen.
Only posting to a conversation waits differently. send on samuraiapp_conversation returns after the agent's
reply is finalized — unlike other tools, it does not return immediately after sending.
There is one escape hatch for reaching endpoints not in the manifest: samuraiapp_request, where
list_endpoints lists callable endpoints and call hits one by raw method and path.
Authorization goes through exactly the same path as the other tools, so it widens the surface but not the permissions.
It cannot go outside /api/, and 「接続元の制限」, the single sign-on settings, registering SaaS API credentials, and
removing members are blocked (human decisions, done from the screen).
Your own local Claude Code as a conversation's harness
When a conversation's 「実行する AI」 is 「手元の Claude Code」 (samuraiapp tunnel register --agent claude-code,
see references/cli.md), the same endpoint and the same tool set above is what that session reaches —
nothing more. Its permission prompts arrive as one extra tool, samuraiapp_permission, which only that
session's token can call; it is not offered to ordinary MCP clients. This option only exists for your own
private conversation started from / — team and channel conversations never offer it.
That session's token cannot answer or loosen approvals. If an approval card is answered after the session stopped
waiting (about 50 seconds), the answer still counts: the same action asked again — in the same turn or the next
message — goes through without a new card. samuraiapp_conversation send refuses such a conversation; its
turns are sent from the Samurai App screen only.
Approvals are not passed automatically
When an agent stops to ask for approval, there is no mechanism to approve automatically via MCP. The pending approval stays in the conversation as is; answer it with the approval tool or press it on screen.
Approval responses are recorded as the token owner.
What it cannot do
- Setting up a connection itself requires a browser (because of OAuth to external services)
- Secrets cannot be read. Only stored and made available for use
- It does not open SSE sessions (each request is self-contained)
Frequently asked
- Cannot connect — check the spelling of the tenant ID in the URL. If it still fails, sign in again
- Sign-in works but nothing can be read — the workspace has 「接続元の制限」 in effect, and the current network is not allowed. It goes through exactly the same check as signing in on screen, so reconnect from an allowed network or ask an administrator to allow it
- Tools do not appear — right after registering the connector, they do not appear until the client refetches the list
- Want to use another tenant too — add one more connector. Only the tenant ID in the URL differs
- Confused with connecting Samurai App to external MCP servers — that is the opposite direction, handled on screen at
/settings/connections. This covers the side where Samurai App is the server