Connect Claude and other AI apps (MCP)

AI MCP lets an AI app such as Claude work with your Joy One workspace in plain language. You can ask it to find a customer, list your open tasks, check today’s bookings, or create a task, and it uses your live workspace data.

It connects through the open Model Context Protocol  (MCP). Joy One’s MCP server is hosted by Joy One at https://api.joyone.vn/mcp. You do not install anything on your side.

What you can ask for

What is available depends on the modules turned on for your workspace and on your role. These are the main areas:

• Customers: search, open a customer by code, create, archive
• Bookings: list bookings, create a booking
• Tasks and projects: list, search, open by code, create, update, move between statuses, add a comment or extra description; manage projects and folders
• Tags and categories: list, create, apply tags in bulk, organize categories
• Products and stock: search and update products, check stock, record stock in and out, stock transfers, combos
• Tickets: list, create, update, calculate a ticket
• Receipts: create and review income and expense records, record a partial payment, mark an expense as disbursed, revert a payment
• Posts and partners: search, read, create, update, archive
• Files for posts and other records: import a public URL into the workspace; clients with local-file and HTTP support can also prepare and complete a direct upload
• Reports: a summary of key business numbers, or one metric with a breakdown
• Workspace: branch information and the member list

Add files to the workspace

Joy One provides three MCP file tools:

• import_file_from_url downloads a public HTTP or HTTPS URL into workspace storage and returns only when the file is ready.
• prepare_file_upload creates a short-lived upload session for a local file.
• complete_file_upload verifies the uploaded bytes and creates the workspace file.

The file tools publish an outputSchema and return the same object in MCP structuredContent. They also include serialized JSON text for clients that do not use structured results.

Workflow 1: import a public URL

Ask the AI app to import the URL. This is the most portable workflow because it only needs an ordinary MCP tool call. Joy One downloads and checks the file, stores it in the workspace, and returns a stable jof:// reference.

Private-network addresses, unsafe redirects, empty files, unsupported content, timeouts and files over the configured limit are rejected.

Workflow 2: upload with a signed PUT

A client that can read a local file and make HTTP requests can:

1. Call prepare_file_upload with the file name and exact expectedSize.
2. Send the bytes to the returned URL when uploadMethod is PUT, including every required header.
3. Call complete_file_upload with the returned completion token.

Workflow 3: upload with multipart form data

When prepare_file_upload returns POST_MULTIPART, the client must submit the file to uploadUrl with the returned formField name and every returned header, then call complete_file_upload.

File limits

The default URL-import limit is 20 MiB, with a 30-second timeout and at most 3 redirects. The default direct-upload limit is 50 MiB. Upload sessions expire after 20 minutes. A Joy One deployment may use different configured limits.

Do not send a file as base64 in a tool call. Signed URLs and completion tokens are temporary secrets and should not be pasted into a Post or shared with another person.

Use imported files in Posts

File tools return a stable reference such as:

jof://507f1f77bcf86cd799439011.png

Use the returned fileRef as a Post thumbnail or in Markdown:

{
  "thumbnail": "jof://507f1f77bcf86cd799439011.png",
  "contentMarkdown": "![Article cover](jof://507f1f77bcf86cd799439011.png)"
}

Always keep the canonical jof:// value. Do not save the upload URL, completion token, a temporary /files/access/... URL, or the original source URL in the Post. Joy One validates the workspace file and resolves the public delivery URL separately.

What it can and cannot see

The AI app acts as you. It can only see and change what your role and permissions already allow in Joy One. If you cannot open a screen in the app, the AI app cannot read or change that data either.

Anything it creates, updates, or deletes is a real change to your workspace. Review what it proposes before you confirm it in the AI app.

Connect Claude

You sign in with your Joy One account. You do not need to copy any key.

1. In Claude, open Settings → Connectors → Add custom connector.
2. Enter the server address https://api.joyone.vn/mcp and save.
3. Claude opens Joy One in your browser. Sign in if you are not signed in yet.
4. Choose the workspace Claude may use. If you turned on two-factor authentication, enter a code from your authenticator app.
5. Press Allow. You return to Claude, and the connector is ready.
6. Start a conversation and ask something such as “Show my open tasks”.

Each connection is linked to one workspace. To use Claude with another workspace, add the connector again and choose that workspace. If a workspace requires two-factor authentication, turn it on for your account first.

See and disconnect connected apps

Open AI MCP from your account menu (or go to https://app.joyone.vn/profile/mcp). Connected apps lists every AI app you have allowed in the current workspace, with when it connected and when it was last used. Press Disconnect to end its access immediately. You can connect it again at any time.

Each time an app is connected, Joy One sends you an inbox notification and an email with the app name, the workspace and how to disconnect it. If you did not make the connection, disconnect it right away and change your password.

Access also ends by itself if you are blocked, removed or leave the workspace, or if you change your password.

Use a key instead (for scripts and other tools)

Some tools cannot sign in through a browser, for example scripts, command-line agents or harnesses that only accept a URL or a header. They can use a personal API key instead.

1. Open AI MCP and press Generate Key.
2. Copy the Connection URL. It is shown only once. If you lose it, generate a new key.
3. Add the connection URL to your tool. Tools that can set request headers can instead use https://api.joyone.vn/mcp with the header Authorization: Bearer <your key>, where the key is the part after token= in the connection URL.

One key at a time

Each member has one active key at a time. A key belongs to you, not to the workspace.

• Regenerate: the old connection URL stops working immediately. Update every tool that used it.
• Revoke: the connection URL stops working immediately. You can generate a new key whenever you like.

Keys and connected apps are separate. Regenerating a key does not disconnect apps that signed in, and disconnecting an app does not affect your key.

Privacy

• Joy One returns data to the AI app only when it asks for it during a conversation, and only data you are allowed to see.
• Joy One does not store the content of your conversations with the AI app. It keeps only the name of each connected app, when it connected and was last used, and the workspace it is linked to.
• What the AI app does with the data you receive is governed by that app’s own privacy terms.

If something does not work

• “Unauthorized” or the app asks you to sign in again: the connection was disconnected, you changed your password, or the key was revoked or regenerated. Connect the app again or generate a new key.
• A tool is missing: your workspace may not have that module turned on, or your role does not include that permission. Ask a workspace admin.
• The AI app cannot connect: check that the server address is exactly https://api.joyone.vn/mcp. If you use a key, check that the full connection URL was pasted, including the ?token= part.
• The approval screen says the request expired: start the connection again from your AI app.
• I cannot press Allow: your workspace may require two-factor authentication, or you have it turned on and must enter a code. If you just signed in with the same code, wait for the next one.