MCP / Tools

Available Apps

How It Works

OAuth Connection Flow

End-User Endpoints

// Server action or backend route
const res = await fetch(
  "https://mcp.assistiv.ai/oauth/authorize?app=github",
  {
    headers: { Authorization: `Bearer ${endUserApiKey}` },
    redirect: "manual",
  }
);
const authorizeUrl = res.headers.get("location");
// Redirect the browser: window.location.href = authorizeUrl

Handling the OAuth Landing Page

After OAuth completes, the MCP service redirects the end user's browser to {base}/mcp/oauth-callback with query parameters describing the outcome.

// e.g. app/mcp/oauth-callback/page.tsx (Next.js)
export default function OAuthCallback({
  searchParams,
}: {
  searchParams: { app?: string; status?: string; error?: string; error_description?: string };
}) {
  const { app, status, error, error_description } = searchParams;
  if (status === "connected") {
    return <p>{app} connected successfully. You can close this tab.</p>;
  }
  return (
    <div>
      <p>Failed to connect {app}: {error}</p>
      {error_description && <p>{error_description}</p>}
    </div>
  );
}

Per-App MCP URLs

Once an end user has connected apps, fetch their scoped MCP config. Each connected app gets its own URL — you choose which apps the model can see.

// GET /v1/me/mcp-config
{
  "standard": {
    "github": {
      "transport": "streamable_http",
      "url": "https://mcp.assistiv.ai/mcp/github",
      "headers": { "Authorization": "Bearer sk-eu_..."}
    },
    "slack": {
      "transport": "streamable_http",
      "url": "https://mcp.assistiv.ai/mcp/slack",
      "headers": { "Authorization": "Bearer sk-eu_..."}
    }
  },
  "openai": [
    {
      "type": "mcp",
      "server_label": "github",
      "server_url": "https://mcp.assistiv.ai/mcp/github",
      "authorization": "Bearer sk-eu_..."},
    {
      "type": "mcp",
      "server_label": "slack",
      "server_url": "https://mcp.assistiv.ai/mcp/slack",
      "authorization": "Bearer sk-eu_..."}
  ]
}

Hosted MCP via Responses API

Pass per-app MCP tool items in your /v1/responses request. You pick which apps the model can see on each call.

curl -X POST https://api.assistiv.ai/v1/responses \
  -H "Authorization: Bearer sk-eu_end_user_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Create a GitHub issue in my-org/test-repo titled hello",
    "tools": [
      {
        "type": "mcp",
        "server_label": "github",
        "server_url": "https://mcp.assistiv.ai/mcp/github",
        "authorization": "Bearer sk-eu_end_user_key"
      }
    ]
  }'

// Include specific apps:
tools: config.openai.filter(t => ["github", "slack"].includes(t.server_label))

// Or include all connected apps:
tools: config.openai

Hybrid Execution Semantics

• The model is invoked with both your function tools (if any) and the MCP tools.
• Only MCP tool calls: backend executes them inline, re-invokes the model. Loop continues until a final answer.
• Any function tool call: loop returns immediately so your platform can handle it. MCP calls in the same turn are NOT executed.
• Maximum loop depth: 10 iterations. Each turn debits wallet/budget normally.

Response Output Items

{
  "id": "resp_abc",
  "object": "response",
  "status": "completed",
  "model": "gpt-4o",
  "output": [
    {
      "type": "mcp_call",
      "id": "mcp_xyz",
      "server_label": "github",
      "name": "github_create_issue",
      "arguments": "{\"owner\":\"my-org\",\"repo\":\"test-repo\",\"title\":\"hello\"}",
      "output": "Issue #42 created",
      "status": "completed"},
    {
      "type": "message",
      "id": "msg_abc",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "Done — issue #42 is open."}
      ]
    }
  ],
  "usage": { "input_tokens": 120, "output_tokens": 35, "total_tokens": 155 }
}

Streaming Events

• response.mcp_list_tools.in_progress / .completed — tool discovery
• response.output_item.added (with item.type: "mcp_call")
• response.mcp_call_arguments.delta / .done
• response.mcp_call.in_progress / .completed
• response.output_text.delta — final answer

Direct Protocol Access (Advanced)

POST mcp.assistiv.ai/mcp/{app_slug} is the raw JSON-RPC 2.0 endpoint over Streamable HTTP transport. Use it only if you're implementing your own MCP client. Requires the standard MCP session handshake (initialize → notifications/initialized → tools/list → tools/call) and emits an mcp-session-id response header. Session TTL is 30 minutes. Tool names follow the pattern {app_slug}_{tool_name} (dashes converted to underscores).

Activating MCP apps for your platform

Decide which MCP apps (GitHub, Slack, Zoho Mail, Zendesk, …) your end users can connect, supply your OAuth Client ID and Secret, and set your platform's OAuth landing URL. This is a one-time setup per app, handled in the dashboard so the OAuth secret never round-trips through your own code.

Reference Endpoints