Quickstart
Optiak gives your application two OpenAI-compatible endpoints for inference and one MCP endpoint for tools. Set up a model for your application and test Inference. You can also configure tools and run the optional MCP check. This guide walks you through all these steps, starting with the required organization Setup preliminaries.
Required role
Applies to
| Use | Base URL | Endpoint | Protocol |
|---|---|---|---|
| Generate a response from messages | https://api.optiak.dev/v1 | POST /chat/completions | OpenAI-compatible Chat Completions |
| Generate a response from an input | https://api.optiak.dev/v1 | POST /responses | OpenAI-compatible Responses |
| Discover and call tools | https://api-mcp.optiak.dev | POST /mcp | Model Context Protocol (MCP) over Streamable HTTP |
Setup
Before you begin, you need Organization Admin access, a terminal with curl and credentials for your chosen model provider or custom endpoint.
Organization setup
The organization decides which models and tools applications may use. Configure these once in Company setup. See how organization and application settings work together.
For inference (required), choose a model from a supported provider or a custom provider with an OpenAI-compatible API. This guide uses OpenAI as an example.
- Open Company setup → Providers, select Add provider and choose your provider from the catalog. For the OpenAI example, choose OpenAI, enter a Name, paste your OpenAI provider key, set Scope to the Default project and select Add key.
- Open Company setup → Models and turn on Enabled for your chosen model. Make sure to choose a model that supports the inference endpoint you want to test; this is displayed as capability tags associated with each model on the list, the relevant ones are
Chat completionandResponses API.
See Models and Connect Model APIs for configuration and credentials.
For tools (optional), choose a supported MCP server. This guide uses Exa web search as an example; you can connect another server and use its tools and input schema instead. Skip this part if you only want to test inference.
- Open Company setup → Tools, select Add tools and choose Exa. Give it a name, such as
Quickstart search. - Follow Connect Exa to connect the server.
- Select Discover tools. Under Tool access, choose Only selected tools and select at least
web_search_exafor this example. - Set Scope to the Default project, which is where you will create your application later, keep Setup active on and save.
See Tools for access rules and Connect MCP Servers for other servers and their authentication requirements.
Application setup
An application selects what it needs from the organization's allowed models and tools. It belongs to a project and has its own API keys. See Applications.
- Open Projects, select the Default project and select Create application. Enter a name in General.
- In Capabilities, enable at least one model your organization allows. Use the model you enabled above; this is required for the inference check.
- Optional: if you configured Exa, in Data & tools → Tools, select Add tools and choose
Quickstart searchor the name you gave that server. Keep Enable server on, choose Only selected tools and select at leastweb_search_exa. Otherwise, skip tool configuration. - In Access, turn on Create an API key with the application, enter a key name and select Create application.
- Copy the key from Credentials and store it securely. Optiak shows the full value only once.
Set your Optiak application API key in your terminal. Both APIs use it in the Authorization: Bearer header:
export OPTIAK_API_KEY="<your-application-api-key>"
Inference
Required check. Send a request to the model you enabled during setup using either OpenAI-compatible endpoint. Use a model ID returned by the application’s model list below.
Set your inference base URL
export OPTIAK_BASE_URL="https://api.optiak.dev/v1"
List available models
Check which models this application can use:
curl "$OPTIAK_BASE_URL/models" \
-H "Authorization: Bearer $OPTIAK_API_KEY"
The response has a data array containing the models this application can call. Choose a model and replace <model-id> in the request examples below with its full id, exactly as returned.
The features array lists the endpoints each model supports: chat_completion_api for Chat Completions and responses_api for Responses. See Using the API for the response fields. If the list is empty, check that the model is enabled in both Company setup and the application and that its provider is connected.
Send a Chat Completions request
Send a chat completion using your chosen model ID. The model must support Chat Completions.
curl "$OPTIAK_BASE_URL/chat/completions" \
-H "Authorization: Bearer $OPTIAK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<model-id>",
"messages": [
{ "role": "user", "content": "Write a one-sentence welcome message for new users." }
]
}'
The response has the same shape as an OpenAI chat completion.
Send a Responses request
If your model supports Responses, use the same key and model ID with an input instead of a messages array:
curl "$OPTIAK_BASE_URL/responses" \
-H "Authorization: Bearer $OPTIAK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<model-id>",
"input": "Write a one-sentence welcome message for new users."
}'
For request and response formats, see Using the API.
Inspect the inference trace
- In the console, open your application, then Requests.
- Find your request in the list. Each row shows its status, model, latency, tokens and cost.
- Select the request to open its trace: the steps the request went through in the Gateway, with their timing.
You've completed the inference check. Continue with MCP if you configured tools, or go to Next steps.
MCP
Optional check. Continue only if you configured a server and enabled its tools for the application. This example searches the web with Exa. If you chose another server, use one of its returned tool names and its input schema.
Configure your AI application's MCP connection separately from its model connection. Use the same application API key for both. Your application coordinates model requests and MCP tool calls; see How applications use tools. Here, you make a test call directly with curl.
Set your MCP endpoint
Use the Optiak application API key from Application setup and the MCP endpoint:
export OPTIAK_MCP_URL="https://api-mcp.optiak.dev/mcp"
List available tools
Send the MCP tools/list request:
curl "$OPTIAK_MCP_URL" \
-H "Authorization: Bearer $OPTIAK_API_KEY" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
The response's result.tools array contains each tool's name, description and inputSchema. Find web_search_exa and copy its full name, including the suffix Optiak adds to distinguish servers.
Set the name returned by your request, replacing the placeholder:
export OPTIAK_TOOL_NAME="<full web_search_exa name from result.tools>"
Call your first tool
Send tools/call with that name and the arguments required by its input schema. Exa's search tool accepts a query and an optional numResults; this example requests three results:
curl "$OPTIAK_MCP_URL" \
-H "Authorization: Bearer $OPTIAK_API_KEY" \
-H "Accept: application/json, text/event-stream" \
-H "Content-Type: application/json" \
--data @- <<JSON
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "$OPTIAK_TOOL_NAME",
"arguments": {
"query": "Model Context Protocol official documentation",
"numResults": 3
}
}
}
JSON
See the result
A successful search returns results in result.content; result.isError is absent or false. Look for page titles, URLs and content excerpts. The results vary as the web changes. This confirms that your application called a tool through Optiak.
To connect an MCP client, use the same URL, Streamable HTTP transport and your Optiak application API key in the Authorization: Bearer <optiak-application-api-key> header. Check the relevant documentation for your client for how to configure the endpoint URL and API key.
Troubleshooting
These checks apply to both inference requests and MCP tool calls:
| What you see | What to check |
|---|---|
| Authentication is rejected | Use the Optiak application API key and confirm it has not expired or been revoked. |
| An HTTP or connection error | Check the URL for the relevant API and the bearer header. Read the returned error message for details. |
MCP tool calls
| What you see | What to check |
|---|---|
| No tools, or the example tool is missing | Check the server's scope, organization and application tool selections, enabled state and data governance rules. See tool access conditions. |
error in the response, or result.isError is true | Read the returned message, check the full tool name and input schema, and confirm the upstream server is available. |
Next steps
- Models: configure the models your application can use.
- Tools: understand tool access and gateway behavior.
- Connect MCP Servers: connect your organization's services.
- Gateway overview: understand how Optiak handles inference requests and tool calls.