Client Connection Guide
Learn how to configure your frontend and backend applications to broadcast and listen for sub-millisecond events with OsciWave.
Guide Navigation
1. Quickstart & API Credentials
To connect to OsciWave, obtain your credentials from your account dashboard:
Add these environment variables to your application's .env file:
REVERB_APP_ID=ow_app_849204 REVERB_APP_KEY=ow_key_7392019482736451 REVERB_APP_SECRET=sk_sec_9938201928475612 REVERB_HOST=ws.osciwave.com REVERB_PORT=443 REVERB_SERVER_PORT=8081 REVERB_SCHEME="https"
2. AI Agent MCP Setup
Generate a workspace-scoped agent API key from Settings → API keys, then connect your client to the Streamable HTTP endpoint below.
Cursor
Save as .cursor/mcp.json for the project or ~/.cursor/mcp.json globally.
{
"mcpServers": {
"osciwave": {
"url": "https://osciwave.com/mcp",
"headers": {
"Authorization": "Bearer ${env:OSCIWAVE_MCP_TOKEN}"
}
}
}
}
Claude Code
Save as .mcp.json in the project root; Claude expands the token from your environment.
{
"mcpServers": {
"osciwave": {
"type": "http",
"url": "https://osciwave.com/mcp",
"headers": {
"Authorization": "Bearer ${OSCIWAVE_MCP_TOKEN}"
}
}
}
}
VS Code with GitHub Copilot
Save as .vscode/mcp.json. VS Code prompts for the token and keeps it out of the file.
{
"servers": {
"osciwave": {
"type": "http",
"url": "https://osciwave.com/mcp",
"headers": {
"Authorization": "Bearer ${input:osciwaveToken}"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "osciwaveToken",
"description": "OsciWave agent API key",
"password": true
}
]
}
Gemini CLI
Add this to .gemini/settings.json for the project or ~/.gemini/settings.json globally.
{
"mcpServers": {
"osciwave": {
"httpUrl": "https://osciwave.com/mcp",
"headers": {
"Authorization": "Bearer ${OSCIWAVE_MCP_TOKEN}"
}
}
}
}
Codex CLI, IDE extension, and ChatGPT desktop
Codex uses TOML rather than JSON. Add this to ~/.codex/config.toml or a trusted project’s .codex/config.toml; the same configuration is shared with the Codex IDE extension and ChatGPT desktop app.
[mcp_servers.osciwave] url = "https://osciwave.com/mcp" bearer_token_env_var = "OSCIWAVE_MCP_TOKEN"
What the agent can do
- Call
download_skillto load the OsciWave workflow. - Call
create_projectwith a GitHub, GitLab, file, URL, or other stable source identity. - Call
install_reverbfor dependency, environment, and verification steps. - Call
connect_projectto retrieve the authenticated project configuration.
3. Connecting via Laravel Echo
OsciWave is fully compatible with `laravel-echo` and `pusher-js`. Install the dependencies in your frontend project:
Configure `resources/js/bootstrap.js` with your OsciWave socket parameters:
import Echo from 'laravel-echo';
import Pusher from 'pusher-js';
window.Pusher = Pusher;
window.Echo = new Echo({
broadcaster: 'reverb',
key: import.meta.env.VITE_OSCIWAVE_APP_KEY,
wsHost: import.meta.env.VITE_OSCIWAVE_HOST ?? 'ws.osciwave.com',
wssPort: import.meta.env.VITE_OSCIWAVE_PORT ?? 443,
forceTLS: true,
enabledTransports: ['ws', 'wss'],
});
// Listening for real-time events
window.Echo.channel('orders')
.listen('OrderProcessed', (e) => {
console.log('Order event received:', e);
});
4. Connecting via Standard Pusher JS
You can also connect directly using the vanilla `pusher-js` client library without Laravel Echo:
import Pusher from 'pusher-js';
const pusher = new Pusher('ow_key_7392019482736451', {
wsHost: 'ws.osciwave.com',
wssPort: 443,
forceTLS: true,
disableStats: true,
enabledTransports: ['ws', 'wss']
});
const channel = pusher.subscribe('osciwave-public');
channel.bind('ping', function(data) {
alert(JSON.stringify(data));
});
5. REST Broadcast API Endpoint
To publish events from any backend language (PHP, Node.js, Python, Go, Ruby), send an HTTP POST request to the REST broadcast endpoint:
Example `curl` payload request:
curl -X POST "https://ws.osciwave.com/api/apps/ow_app_849204/events" \
-H "Content-Type: application/json" \
-H "X-OsciWave-Key: ow_key_7392019482736451" \
-d '{
"channel": "orders",
"name": "OrderProcessed",
"data": {
"order_id": 1042,
"status": "completed",
"amount": 99.00
}
}'
6. Private & Presence Channel Authorization
Private channels require an authorized subscription payload authenticated by an HMAC signature generated by your backend application.
window.Echo.private(`user.${userId}`)
.listen('NotificationSent', (e) => {
console.log(e.notification);
});