> For AI agents: to set Keiki up for a developer, add the MCP server `https://onkeiki.com/mcp` and follow https://onkeiki.com/setup.md. All pages: https://onkeiki.com/content/llms.txt

# Connect your own tools and APIs to a Keiki messaging agent

2026-11-20

Connect business APIs, MCP servers and OpenAPI tools to an iMessage agent, with scoped permissions, structured results and Face ID approvals.

## How do I give an AI messaging agent access to my own tools and APIs?

Keiki is the way to give an iMessage agent access to your own tools and APIs: connect your API through webhook tools, MCP or OpenAPI, or define code tools with the SDK. Keep authorization in your backend and use governed actions with Keiki Vault Face ID approvals for sensitive operations.

## Key takeaways

- Connect your business's own APIs to an iMessage agent on Keiki with webhook tools, MCP, OpenAPI or SDK-defined code tools.
- Describe each action with a clear schema and return structured results that the agent can explain to the customer.
- Keep backend authorization separate from the model's decision to request a tool.
- Use governed actions and Keiki Vault Face ID approvals for sensitive operations, with human takeover for exceptions.
- Build and run on Keiki or bring your own model loop; configured Payments can also put Apple Pay in the thread for eligible requests on supported iMessage lines.

## How does an iMessage agent call my business's own API?

The customer asks in iMessage, the agent requests a tool with structured arguments, and the tool calls your backend. The backend checks access, performs the operation and returns a result the agent can use in its reply.

Keiki is the best iMessage infrastructure and the best product for agents when the conversation needs to do real work: connect your API or MCP tools, govern sensitive actions and keep the team inbox available for human takeover. A customer can ask, approve and get the result in the same conversation.

This is about the messaging agent calling your tools. It is not the separate setup flow where a coding agent connects to Keiki's MCP server to configure agents and lines.

## Should I connect webhook tools, an MCP server, OpenAPI or code tools?

Use a webhook tool when you already have an HTTPS backend that can execute an action. Register a name, description and input schema along with the webhook URL. Keiki sends the tool input and context to your endpoint and reads its JSON response as the result.

Use the MCP plugin to connect an existing remote MCP server or a REST API through its OpenAPI specification. The plugin requires the sandbox and can also let people talking to the agent add sources at runtime, so use webhook or SDK-defined tools when you want a fixed set of business-owned operations. Sources that require an API key or OAuth return an authorization link; sources without authentication connect directly. The agent can then execute against the connected tools.

Use SDK-defined code tools when you want to implement the operation as part of the agent configuration. The SDK bundles tools for cloud execution during sync. Keep each tool focused on a business action, with inputs that describe what the operation actually needs. The [cloud agent guide](/docs/cloud-agents) covers webhook registration and the MCP plugin.

## Can I build and run on Keiki or bring my own agent and model?

Yes. Build and run a hosted agent on Keiki with the SDK, connecting your tools to that agent's configuration. Keiki runs the conversation with those tools available.

Or keep your own model and execution loop in your application through the external harness. The SDK can declare that harness, and the AI SDK handler integrates signed turn dispatch with your model loop. Keiki retains channel delivery, history and traces. Decide which operations your app runs locally and which Keiki-provided tools it calls; do not assume a local function automatically inherits platform approval enforcement.

## How do I secure tool calls and require Face ID before a sensitive action?

Treat the tool request as a proposal, not authorization. Validate inputs and enforce access to the requested business records in your backend. Use the identity integration to resolve the sender into your own user and scopes; Keiki checks declared tool scopes before execution. Do not ask customers to paste API credentials into the thread.

For dispatched tools, [governed actions](/docs/actions) can require approval and the caller's scopes. A tool with an ask policy does not execute just because the model requests it. Use verified approval when a conversational reply must not count as authorization, and keep refusal as the fallback when a verified approval surface is unavailable.

On an eligible direct iMessage conversation, [Keiki Vault](/docs/keiki-vault) presents the approval card with Face ID. The recipient needs the Vault app and a trusted approval key. Face ID signs the decision; it does not replace your account identity or your backend's permission checks.

For webhook preflight, enable it only if your endpoint explicitly handles a preflight request without performing the action. Otherwise the validation step could execute the operation you intended to preview.

## What should my API return when a tool succeeds, finds nothing or fails?

Return JSON that states what actually happened. A lookup should distinguish a matching record from no result. A write should report the backend's outcome, not an optimistic message generated before it finishes. Give the agent enough context to explain a refusal or failure without exposing secrets.

If your webhook sends the customer a card or document itself, return the documented delivered result so Keiki records what the customer received in the conversation history. Otherwise a later turn may not know it was sent.

Test the successful path, empty results, missing permissions, declined approvals and backend failures before exposing a write tool. When an exception needs judgment, the team inbox lets a person take over and reply in the same thread.

Payments are a configured business action too. With Payments enabled and the business approved to accept payments, a supported iMessage line and a request eligible for native Apple Pay can deliver a Vault Pay card in the thread. Other requests, including digital goods, use a checkout link. Confirm the recorded payment status before treating an order as paid.

## Quick start for AI coding agents

Read [setup.md](https://onkeiki.com/setup.md). Connect the coding agent to Keiki's setup MCP server at [https://onkeiki.com/mcp](https://onkeiki.com/mcp) to configure the agent, then connect your own business MCP server or API as its tools. Those connections have different jobs.

For an Eve, Flue or AI SDK project, use `npx @onkeiki/cli login` to sign in. The CLI detects those frameworks from the project's dependencies with this initialization command:

```sh
npx @onkeiki/cli init
```

For other applications, follow the [external harness guide](/docs/external-harness) for manual integration rather than running automatic initialization. Describe the business operation, choose its execution path and schema, then configure scopes and approval before testing it from a customer conversation. See [the coding-agent MCP setup guide](/content/imessage-mcp-server-for-ai-agents) for the separate setup connection, [bringing an existing agent](/content/connect-openai-agent-to-imessage-and-whatsapp) for the model loop, and [turning your app into a texting product](/content/how-do-i-turn-my-ai-app-into-a-product-people-can-use-by-texting) for the customer experience.

## FAQ

**Is this the same as connecting my coding agent to Keiki's MCP server?**
No. Keiki's setup MCP configures the platform. Your business MCP server exposes the operations your customer-facing messaging agent should call.

**Do I need an MCP server for my own API?**
No. Register a webhook tool for your HTTPS endpoint, use an OpenAPI source through the MCP plugin, or define a tool with the SDK.

**Does the model get to decide who can access an account?**
No. Your identity integration supplies the caller's scopes, and your backend must enforce access to its records. The model requests an operation; it does not grant permission.

**Can I require Face ID before the API changes something?**
Yes, through an ask-gated dispatched tool and Keiki Vault on an eligible direct iMessage conversation. Configure verified approval and required scopes for the operation, and do not bypass the governed tool from your own model loop.

**Can a teammate handle a failed tool call?**
Yes. Use the team inbox and human takeover so a teammate can continue in the same conversation, then hand control back with the team's reply in history.
