# Integrate with AI

> Use an AI coding assistant to integrate OTP.ps: a ready prompt, the official Agent Skill, the MCP server, llms.txt and OpenAPI.

OTP.ps is built so an AI coding assistant can integrate it for you: read the docs, write a secure server-side integration in your stack, test it in the sandbox, and give you a production checklist. Everything here is free; you only pay for real text messages.

## The prompt

Open your project in your AI coding assistant and paste:

> Integrate OTP.ps into my application to verify Palestinian mobile numbers using SMS verification codes. Inspect my existing technology stack, follow the official OTP.ps documentation, implement a secure server-side integration, and test it using the sandbox environment before enabling production messaging.

Add your use case at the end, for example *"…to confirm cash-on-delivery orders at checkout"*. Then give the assistant one of the tools below, so it doesn't work from memory.

## The Agent Skill

A folder of instructions, references, tested examples and scripts in the open [Agent Skills](https://agentskills.io) format. It teaches the assistant the whole workflow: inspect the app, choose the architecture, keep the key on the server, normalize numbers, build the send/check endpoints and the form (Arabic RTL and English), handle every error, test with the sandbox numbers, and hand over the checklist. Its scripts check a test key against the sandbox (refusing live keys) and scan the project for leaked keys.

**Claude Code**, for one project (run in the project's folder):

```bash
mkdir -p .claude/skills && curl -fsSL https://otp.ps/skills/otp-integration.tar.gz | tar -xz -C .claude/skills
```

or for all your projects:

```bash
mkdir -p ~/.claude/skills && curl -fsSL https://otp.ps/skills/otp-integration.tar.gz | tar -xz -C ~/.claude/skills
```

Claude Code then uses it whenever you ask for OTP.ps or phone verification.

**Other assistants:** if your tool supports Agent Skills, put the same `otp-integration` folder where it loads skills from (see its documentation). If it doesn't, [download the folder](https://otp.ps/skills/otp-integration.tar.gz) into your project and tell the assistant to follow `otp-integration/SKILL.md`, or tell it to read `https://otp.ps/llms.txt`.

## The MCP server

`https://otp.ps/mcp` (Streamable HTTP, no account needed). It lets the assistant look things up and **try the API in the sandbox** while it works:

| Tool | What it does |
|---|---|
| `get_integration_guide` | A guide for a use case (cash on delivery, registration, passwordless login, phone verification, delivery, appointments) or topic |
| `get_code_example` | Tested code for cURL, TypeScript, Node.js, React, Next.js, PHP, Laravel, Python, WooCommerce, Shopify |
| `get_api_reference` | The API reference, or the OpenAPI document |
| `get_error_reference` | What an error code means and what to do |
| `normalize_phone` | Validates and normalizes a number exactly like the API |
| `get_supported_networks` | Networks, accepted formats, sandbox numbers |
| `send_test_otp`, `verify_test_otp` | Send and check a code in the sandbox: no message is sent, nothing is charged |
| `get_integration_checklist` | The production checklist and security practices |

It also offers every docs page, the OpenAPI document and the Agent Skill as resources, and an `integrate_otp_ps` prompt.

**Claude Code:**

```bash
claude mcp add --transport http otp-ps https://otp.ps/mcp
```

**Other clients** that support remote MCP servers over HTTP use the same address. For example, a `mcp.json`-style configuration:

```json
{ "mcpServers": { "otp-ps": { "url": "https://otp.ps/mcp" } } }
```

and VS Code's `.vscode/mcp.json`:

```json
{ "servers": { "otp-ps": { "type": "http", "url": "https://otp.ps/mcp" } } }
```

Without an account, `send_test_otp` works on the [sandbox numbers](/docs/sandbox) only, in a private sandbox for your connection. To use any number in **your own** sandbox, add your **test** key to the connection, e.g. `claude mcp add --transport http otp-ps https://otp.ps/mcp --header "Authorization: Bearer otp_test_…"`. The MCP server refuses live keys: it can't send real messages or touch your balance.

Your production integration never depends on the MCP server or an AI: it calls the REST API directly.

### Account tools (not available yet)

A second address, `https://otp.ps/mcp/account`, will let an AI tool work on **your own account** after you approve it:

| Tool | Permission |
|---|---|
| `send_otp` (real messages in live mode; requires an idempotency key) | Send codes |
| `verify_otp` | Check codes |
| `get_balance`, `get_usage`, `get_account_limits` | Read balance, usage and limits |

The tool signs in with OAuth. You approve it on OTP.ps while signed in to your dashboard, and choose:
- which permissions it gets;
- test or live mode;
- a daily message limit, which is required for live sending.

Everything it does appears in your **Activity log**, where you can disconnect it at any time.

This is built and tested but **switched off** until OTP.ps finishes its security review. Until then, that address answers "not found".

## Plain documentation for any AI

- [`/llms.txt`](https://otp.ps/llms.txt): what OTP.ps is, the key facts, and an index of every page.
- [`/llms-full.txt`](https://otp.ps/llms-full.txt): all the documentation in one file.
- Any docs page as Markdown: add `.md` to its address, e.g. `https://otp.ps/docs/quickstart.md`.
- [`/openapi.json`](https://otp.ps/openapi.json): the OpenAPI 3.1 contract, built from the API's code.

## What has been tested

| | |
|---|---|
| MCP server | With the official MCP client over HTTP (every tool, resource and prompt), and Claude Code connects to it (`claude mcp list` reports it connected). |
| Account tools (switched off) | The official MCP client completes the whole OAuth sign-in and uses every account tool; Claude Code recognises that `/mcp/account` needs sign-in. |
| Agent Skill | Its scripts and every example are run or syntax-checked against the API on every change; its references are regenerated from these docs. The folder follows the Agent Skills format checked by the tests. |
| Other assistants | Cursor, VS Code, Codex, Windsurf, Lovable and Replit haven't been tested by OTP.ps yet. The configurations above follow their published formats for remote MCP servers. |
