Skip to content
Start for free

Building external tools

For developers building an external tool (MCP server) for Chatbotta bots: when Chatbotta calls your tools and whose identity it uses, and what your server needs so each customer only ever sees their own data.

If you only want to install or set up an external tool, Apps is all you need.

First: Chatbotta isn’t a personal AI assistant

Section titled “First: Chatbotta isn’t a personal AI assistant”

When a personal AI assistant such as ChatGPT or Claude connects to an external tool, the person using it and the person who authorized it are the same. Chatbotta is different: a business sets up the external tool once in its project, and from then on the bot uses it on the business’s behalf to answer many customers it doesn’t know.

So the key question when you design an external tool is: whose credentials does this call use?

  • The business’s shared credentials: whichever customer asks, the bot looks things up with the same business account. Right for data that’s the same for everyone, such as room availability, opening hours or stock.
  • Each customer’s own credentials: each customer first verifies themselves with your service, and when the bot calls on their behalf it sends only that customer’s token. Right for data that differs per person, such as “my orders”, “my bookings” or “my points”, and the only safe way to let customers cancel or change their own records.
  1. Customer → Chatbotta bot: Sends a message on LINE, Messenger, Instagram or website chat
  2. Chatbotta bot: Uses each external tool’s “Purpose” to decide whether to use one, and which
  3. Chatbotta bot → Your MCP server: tools/call (only tools checked in the “Bot” column)
  4. Your MCP server → Chatbotta bot: Returns the result
  5. Chatbotta bot → Customer: Turns it into a normal reply
When a customer’s message needs outside data

Things that affect your design:

  • The tool list is cached. When an external tool is added (or refreshed), Chatbotta calls tools/list once and stores each tool’s name, description and input schema. Every reply uses that cache, and Chatbotta only connects to your server when it actually calls a tool. When your tools change, ask the admin to refresh the tool list in “Settings” › “Copilot and tools”.
  • “Purpose” decides whether the AI thinks of your tool. The “Purpose” the admin writes is the only description the AI sees when choosing among external tools; only after choosing one does it see each tool’s description and schema.
  • Copilot and the bot have separate lists. In the tool list the admin checks the “Copilot” and “Bot” columns separately. Only tools checked for “Bot” appear in conversations with customers, and a tool has to be checked for “Copilot” first. New tools are shared with Copilot only.
  • No connection, no calls. While an external tool’s status isn’t “Connected” (for example “Needs authorization” or “Connection error”), the AI won’t call its tools.
  • Transport: Streamable HTTP, falling back to SSE. Every call opens a new connection; no session is kept.

The admin picks “Authentication” in “Add external tool”. It can’t be changed afterwards; to switch, delete the tool and add it again.

Authentication Whose credentials a call uses Copilot Bot Right for
No authentication (public server) None Yes Yes Public data
OAuth (authorize in the browser) The business’s (an admin authorizes once) Yes Yes Business-level data such as availability or stock
API token / bearer token The business’s (a token the admin pastes, stored encrypted) Yes Yes The same, when the server has no OAuth
Each customer authorizes (OAuth per user) Each customer’s own token No One-to-one chats only Per-person data such as “my orders”

With “OAuth”, an admin authorizes in a pop-up in Chatbotta; the redirect URI is https://app.chatbotta.com/oauth/mcp/callback. Chatbotta keeps the refresh token and renews access automatically.

The first time a customer needs the tool in a conversation, the bot sends them an authorization button. Once they verify on your page, Chatbotta receives an access token for that customer alone and sends it with every call from that chat.

  1. Customer → Chatbotta: “When is the room I booked?”
  2. Chatbotta → Your MCP server: Connects (no token for this customer yet)
  3. Your MCP server → Chatbotta: 401 + WWW-Authenticate (resource_metadata)
  4. Chatbotta → Your authorization server: Reads authorization server metadata, registers a client dynamically
  5. Chatbotta → Customer: Sends an authorization button in the chat (with PKCE and state)
  6. Customer → Your authorization server: Verifies on your page and approves
  7. Your authorization server → Chatbotta: Redirects back to Chatbotta with code and state
  8. Chatbotta → Your authorization server: Exchanges code and code_verifier for an access token
  9. Chatbotta → Your MCP server: tools/call with Authorization: Bearer (this customer’s token)
  10. Chatbotta → Customer: Carries on answering the original question
A customer uses an “Each customer authorizes” tool for the first time

When the customer finishes, their browser shows a confirmation page, and Chatbotta automatically carries on answering the message they sent; they don’t need to go back and ask again.

Implement the MCP authorization spec; Chatbotta runs this flow with the official MCP SDK.

  • MCP endpoint: Streamable HTTP (or SSE). For a request with no token or an invalid one, return 401 with a WWW-Authenticate header whose resource_metadata points to your protected resource metadata (RFC 9728). Without it, Chatbotta tries /.well-known/oauth-protected-resource.

  • Authorization server metadata (RFC 8414): /.well-known/oauth-authorization-server.

  • Dynamic client registration (RFC 7591). Chatbotta registers with:

    {
    "client_name": "Chatbotta",
    "redirect_uris": ["https://api.chatbotta.com/api/mcp/customerOAuth/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
    }
  • Authorization code + PKCE (S256): Chatbotta is a public client and sends no client secret. When protected resource metadata exists, authorization and token requests include the resource parameter (RFC 8707).

  • Redirect URI: https://api.chatbotta.com/api/mcp/customerOAuth/callback, with code and state.

If your server doesn’t support dynamic registration, the admin can check “Use a manually registered OAuth app (the server doesn’t support automatic registration)” and enter the client ID, client secret, authorization URL and token URL. Chatbotta then builds the authorization URL itself (response_type, client_id, redirect_uri, state; no scope, no PKCE) and sends client_id and client_secret in the form body when exchanging the code. The redirect URI is the same.

  • Chatbotta doesn’t send you the customer’s identity. You don’t receive their LINE user ID, name or phone number; the token is your only way of knowing which customer this is. So your authorization page has to verify the customer itself, for example with an SMS code to their phone or by signing in to their account with you.
  • Decide identity from the token only. Don’t trust member numbers, phone numbers or similar fields in tool arguments to decide whose data to return: the AI fills in arguments, and a customer can ask it to fill in someone else’s.
  • Your authorization page opens in the chat app’s in-app browser (LINE, for example). Customers are usually on a phone and have never signed in to your site. Make sure the whole flow works on phones and in in-app browsers.
  • Tokens are bound to “this chat × this external tool” and stored encrypted. Someone who writes in on LINE and on website chat is in two chats and authorizes in each.
  • Tokens aren’t renewed. When one expires, Chatbotta asks the customer to authorize again the next time it’s needed. Return expires_in in the token response and choose a lifetime that suits your security needs; calls with a token you’ve revoked fail until it expires.
  • If the admin changes the server URL, every customer’s token is deleted, so tokens are never sent to a new host.
  • If a tool result contains the token, Chatbotta masks it before saving the conversation log. Still, never return credentials in results.
  • One-to-one chats only. These tools don’t appear in LINE groups or multi-person chats, because it isn’t clear which customer is asking.
  • Copilot can’t call them. Copilot is for admins and has no customer behind it; for admin tools, add a separate external tool that uses business credentials.
  • You can add the same service twice: one with “OAuth” for Copilot to manage things, one with “Each customer authorizes” for the bot to answer customers. Their permissions are completely separate.

This method has no business-level credentials, so there’s no tool list right after adding, and the status is “No customer has verified yet”.

  1. On the external tool’s card, the admin selects “Test connection” and goes through authorization with their own account in a new tab.

  2. When authorization completes, Chatbotta calls tools/list with the new token, the status becomes “Connected” and every tool is shared with the bot automatically (each call is already limited to the customer’s own permissions). Back in “Copilot and tools”, select “Refresh status” to see the tool list; uncheck any tool in the “Bot” column you don’t want to share.

  3. When your tools change later, refresh the tool list: Chatbotta borrows one authorized customer’s token to call tools/list, and uses it for nothing else.

Without “Test connection”, the tool list is fetched when the first customer authorizes; until then the status isn’t “Connected” and the bot won’t use the tool.

Asking customers for details (elicitation)

Section titled “Asking customers for details (elicitation)”

When a tool finds partway through that it needs more from the customer, use MCP’s elicitation/create in form mode. This works only with “Each customer authorizes” tools.

Most details belong in tool arguments, not elicitation. Things like an order number, a date or a party size, which say what this call is about, go in your input schema as required fields; the AI asks the customer first and fills them in.

Elicitation fits when the detail is:

  • Needed only in some cases: your server can’t tell whether to ask until it has looked things up. For example, when creating an order you find this customer has no delivery address yet, so you ask; customers who already have one aren’t asked.
  • Worth remembering: the answer is kept for this chat, and later elicitations for the same field are answered from memory, so the customer doesn’t repeat themselves.
  • Better not filled in by the AI: the answer comes straight from the customer’s own message, so the AI can’t reword, guess or swap it.

Conversations are asynchronous: the customer’s answer arrives in a later message, and Chatbotta can’t keep your tool call waiting. So Chatbotta declines first, has the bot ask the customer, and answers on the next call:

  1. Chatbotta → Your MCP server: tools/call create_order
  2. Your MCP server → Chatbotta: elicitation/create: “Please provide a delivery address” (field shipping_address)
  3. Chatbotta → Your MCP server: decline (no shipping_address for this chat yet)
  4. Chatbotta → Customer: Asks for the delivery address naturally
  5. Customer → Chatbotta: “100 Songren Road, Taipei”
  6. Chatbotta: Stores this message as shipping_address (encrypted)
  7. Chatbotta → Your MCP server: tools/call create_order again
  8. Your MCP server → Chatbotta: elicitation/create (same field)
  9. Chatbotta → Your MCP server: accept: shipping_address = the customer’s message
  10. Your MCP server → Chatbotta: Returns the order
Creating an order for a customer with no delivery address yet

When implementing it:

  • Ask for one field at a time. If requestedSchema.properties has more than one field, Chatbotta declines.
  • URL mode isn’t supported (mode: "url") and is always declined. To send customers to a web page, use the authorization flow.
  • What’s stored is the customer’s whole message, not just the part you need. They might reply “send it to 100 Songren Road, Taipei, thanks”, so extract and validate it on your server, and elicit again or return a clear error when it doesn’t fit.
  • On decline, finish the call normally (a result or an error both work) instead of waiting. Chatbotta ignores that result and has the bot ask the customer.
  • Answers are remembered per chat, and later elicitations for the same field name are answered from memory. Keep field names stable, and don’t reuse a field name for something different.
  • Write tool descriptions for the AI: say when to use the tool, which arguments it needs and what it returns. The AI decides whether to call it and how to fill it in from these words alone.
  • Validate arguments on your server: Chatbotta removes format and pattern from your schema but still checks types and required fields. For a bad value, return a short, readable error (for example “The date must be YYYY-MM-DD”) and the AI will correct it and retry.
  • Keep results small: Chatbotta turns content into text for the AI. Return only the fields needed to answer, not whole raw records.
  • One tool, one job: keep “check availability”, “create order” and “cancel order” separate so the admin can share only the safe ones with the bot.
  • Let changes be confirmed: before creating an order, for example, return a summary so the AI can confirm it with the customer.
  1. In your own project, add your server URL under “Settings” › “Copilot and tools” › “Add external tool”. A server in development has to be reachable from the internet, for example through a tunnelling service.

  2. With “Each customer authorizes”, select “Test connection”, authorize with your own account (check the page works on a phone too), then select “Refresh status”.

  3. Check the tools to share in the “Bot” column of the tool list and select “Save”.

  4. Ask a question that needs your tool in “Test” in the right-hand panel. The test chat is its own one-to-one chat, so “Each customer authorizes” tools send an authorization button there, just as they would for a real customer.

If the bot doesn’t use your tool, check in this order: the status is “Connected”, the tool is checked for “Bot”, and “Purpose” says clearly when to use it.