# 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**