Complete MCP OAuth Flow

Used to complete OAuth 2.1 Authorization Code flow for an MCP (Model Context Protocol) server. Call this endpoint with the authorization code received from the OAuth callback to exchange it for access and refresh tokens.

API Endpoint

Property	Value
Request Method	POST
Request URL	https://api.seliseblocks.com/tools/{tool_id}/complete-oauth

Request

Request Example

curl -X POST 'https://api.seliseblocks.com/tools/{tool_id}/complete-oauth' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "authorization_code_from_callback",
    "state": "state_value_from_initiate",
    "project_key": "YOUR_PROJECT_KEY"
  }'

Path Parameters

Field	Type	Required	Description
tool_id	string	Yes	The unique identifier of the MCP server tool.

Request Headers

Field	Type	Required	Description
accept	string	Yes	Accepted response format. Use application/json
Content-Type	application/json	Yes	Data type, must be application/json.

Request Body

Request Body Schema

{
  "code": "string",
  "state": "string",
  "project_key": "string"
}

Request Body Parameters

Field	Type	Required	Description
code	string	Yes	Authorization code received from the OAuth callback redirect.
state	string	Yes	State parameter used for CSRF validation (must match the value from initiate-oauth).
project_key	string	Yes	The project key for your project.

note

OAuth Completion Requirements

• The authorization code is single-use and expires quickly (typically 5-10 minutes)
• The state parameter must match the value generated during the initiate-oauth call
• PKCE code verifier will be automatically used if PKCE was enabled during initiation
• Both access tokens and refresh tokens will be securely stored after successful exchange

tip

OAuth Flow Completion Process:

1. User is redirected to your redirect_uri with code and state parameters
2. Extract the code and state from the URL query parameters
3. Call this endpoint with the code, state, and project_key
4. System validates the state parameter for CSRF protection
5. System exchanges the authorization code for tokens at the OAuth provider
6. Access token and refresh token are securely stored
7. MCP server is now fully authenticated and ready for use

The system will:

• Validate the state parameter matches the stored value
• Exchange the authorization code for access and refresh tokens
• Store tokens securely in the MCP server configuration
• Set token expiration times based on OAuth provider response
• Enable automatic token refresh when access tokens expire
• Return success confirmation once authentication is complete

Response

Success Response (200 OK)

Returns an object containing the completion status.

{
  "is_success": true,
  "item_id": "mcp_server_123",
  "detail": "OAuth authentication completed successfully. Access token obtained and stored.",
  "error": {}
}

Response Fields

Field	Type	Description
is_success	boolean	Indicates whether the OAuth flow was completed successfully.
item_id	string	The identifier of the MCP server tool.
detail	string	Success or failure message with additional context.
error	object	Error details if the operation failed (empty if successful).

Error Response (422 Unprocessable Entity)

Returns validation error details when the request body is invalid.

{
  "detail": [
    {
      "loc": [
        "body",
        "state"
      ],
      "msg": "State parameter does not match. Possible CSRF attack.",
      "type": "value_error.csrf"
    }
  ]
}

Error Response Fields

Field	Type	Description
detail	array	Array of validation error objects.
loc	array	Location of the error in the request (e.g., body field).
msg	string	Human-readable error message.
type	string	Error type identifier.

Common Error Scenarios

Error Type	Description	Resolution
Invalid State	State parameter doesn't match stored value	Restart OAuth flow from initiate-oauth endpoint
Expired Code	Authorization code has expired	Restart OAuth flow to get a new authorization code
Invalid Code	Authorization code is invalid or already used	Ensure code is correctly extracted from callback URL
Token Exchange Failed	OAuth provider rejected the token request	Verify OAuth configuration and client credentials

Error Codes

Status Code	Description	Response Type
200	Successful Response	Success
400	Bad Request - Invalid OAuth parameters	Bad Request
401	Unauthorized - OAuth provider rejected request	Unauthorized
404	Not Found - MCP server tool does not exist	Not Found
422	Validation Error - Invalid request parameters or CSRF validation failed	Unprocessable Entity