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).

Platform MCP Configuration

Manage which MCP apps are available to your platform's end users. These can be called with a platform key, or configured via the Assistiv dashboard. OAuth client secrets are encrypted at rest with AES-256-GCM.

curl -X POST https://api.assistiv.ai/v1/platforms/{platformId}/mcp/apps \
  -H "Authorization: Bearer sk-plat_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_slug": "github",
    "display_name": "GitHub",
    "oauth_client_id": "Iv1.abc123",
    "oauth_client_secret": "secret_xyz",
    "redirect_url": "https://my-saas.com",
    "scopes": ["repo", "user"]
  }'

curl -X PATCH https://api.assistiv.ai/v1/platforms/{platformId}/mcp/apps/github \
  -H "Authorization: Bearer sk-plat_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://new-domain.com" }'

curl -X DELETE "https://api.assistiv.ai/v1/platforms/{platformId}/mcp/apps?app_slug=github" \
  -H "Authorization: Bearer sk-plat_your_key"

Reference Endpoints